@cueframe/kernel 0.2.2 → 0.2.3

package/dist/_members/composition/scene/preparedRender.d.ts

@@ -0,0 +1,239 @@
+import type { SceneBakeScaleSelection } from "./resolution.js";
+import type { SceneChannelV2, SceneObjectV2, SceneShotSpecV2, SceneSurfaceBindingV2, SceneVec3 } from "./schema.js";
+import type { SceneSeparationResultV2 } from "./constraints.js";
+import { type SceneSealedVideoScheduleV1, type SceneVerifiedPresentationIndexV1 } from "./videoSchedule.js";
+export type ScenePreparedJson = null | boolean | number | string | ScenePreparedJson[] | {
+    [key: string]: ScenePreparedJson;
+};
+export interface SceneExactRateV1 {
+    num: number;
+    den: number;
+}
+export interface SceneBuilderPartDescriptorV1 {
+    partId: string;
+    materialRole: string;
+    triangles: number;
+    mounted: boolean;
+}
+export interface SceneBuilderSlotDescriptorV1 {
+    slot: string;
+    attachment: {
+        partId: string;
+        materialRole: string;
+    };
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    projectionQuad: readonly [SceneVec3, SceneVec3, SceneVec3, SceneVec3];
+    uvOrigin: "top-left" | "bottom-left";
+    fit: "contain" | "cover" | "stretch";
+    alpha: "opaque" | "straight" | "premultiplied";
+    depth: "write" | "test-only";
+    required: boolean;
+    bakeScales: readonly (2 | 3)[];
+}
+export interface SceneBuilderAllocationDescriptorV1 {
+    owner: string;
+    name: string;
+    domain: "gl" | "cpu";
+    resource: "texture" | "renderbuffer" | "geometry" | "pmrem-source" | "pmrem-target" | "encoded-image" | "decoded-image" | "encoded-video" | "decoded-video";
+    format: string;
+    bytes: number;
+    lifetime: "preparation" | "context";
+}
+export interface SceneBuilderDescriptorV1 {
+    kind: SceneObjectV2["kind"];
+    builderVersion: number;
+    tessellationVersion: number;
+    budgetTriangles: number;
+    parts: readonly SceneBuilderPartDescriptorV1[];
+    surfaceSlots: readonly SceneBuilderSlotDescriptorV1[];
+    materialRoles: readonly string[];
+    localBounds: {
+        center: SceneVec3;
+        halfExtents: SceneVec3;
+    };
+    allocations: readonly SceneBuilderAllocationDescriptorV1[];
+}
+export interface ScenePlanOutputV1 {
+    width: number;
+    height: number;
+    fps: SceneExactRateV1;
+    durationInFrames: number;
+}
+export interface ScenePreparedFontFaceV1 {
+    family: string;
+    weight: number;
+    style: "normal" | "italic";
+    url?: string;
+    paths: readonly string[];
+}
+export interface ScenePreparedObjectV1 {
+    authoredId: string;
+    parentId: string | null;
+    kind: SceneObjectV2["kind"];
+    builder: SceneBuilderDescriptorV1 | null;
+    parts: readonly {
+        id: string;
+        partId: string;
+        materialRole: string;
+        triangles: number;
+        mounted: boolean;
+    }[];
+}
+export interface SceneCaptureIdentityFactsV1 {
+    componentId: string;
+    sourceVersionId: string;
+    params: ScenePreparedJson;
+    assetBindings: ScenePreparedJson;
+    layoutWidth: number;
+    layoutHeight: number;
+    bakeScale: 2 | 3;
+    captureFrame: number;
+    durationInFrames: number;
+    fps: SceneExactRateV1;
+    seed: string;
+    brandFacts: ScenePreparedJson;
+    fontFacts: ScenePreparedJson;
+    mediaFacts: ScenePreparedJson;
+    rasterWidth: number;
+    rasterHeight: number;
+    runtimeIdentity: string;
+    dependencyIdentity: string;
+    browserProduct: string;
+    browserVersion: string;
+    browserExecutableSha256: string;
+    headless: boolean;
+    rasterAffectingFlags: ScenePreparedJson;
+    os: string;
+    arch: string;
+    deviceScaleFactor: number;
+    colorProfile: string;
+    requestedGlBackend: string;
+    actualGlBackend: string;
+    actualRenderer: string;
+    gpuIdentity: string | null;
+}
+export interface SceneVerifiedImageFactsV1 {
+    handle: string;
+    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    byteLength: number;
+    width: number;
+    height: number;
+    decodedSha256: string;
+}
+export interface SceneVerifiedVideoFactsV1 {
+    handle: string;
+    mimeType: "video/mp4" | "video/webm";
+    byteLength: number;
+    width: number;
+    height: number;
+    encodedSha256: string;
+    presentationIndex: SceneVerifiedPresentationIndexV1;
+}
+export interface ScenePreparedSurfaceBaseV1 {
+    path: string;
+    authoredObjectId: string;
+    slot: string;
+    binding: SceneSurfaceBindingV2;
+    descriptor: SceneBuilderSlotDescriptorV1;
+    bakeScale?: 2 | 3;
+    bakeScaleReason?: "declared" | "default-sufficient" | "raised-by-resolution-check";
+    resolutionCheck?: SceneBakeScaleSelection;
+}
+export interface SceneSealedSurfaceV1 extends ScenePreparedSurfaceBaseV1 {
+    realized: {
+        source: "color";
+        color: string;
+    } | {
+        source: "image";
+        image: SceneVerifiedImageFactsV1;
+    } | {
+        source: "video";
+        video: SceneVerifiedVideoFactsV1;
+        schedule: SceneSealedVideoScheduleV1;
+    } | {
+        source: "component";
+        captureIdentitySha256: string;
+        captureIdentityFacts: SceneCaptureIdentityFactsV1;
+        image: SceneVerifiedImageFactsV1 & {
+            mimeType: "image/png";
+        };
+    };
+}
+export interface ScenePlanAllocationLedgerV1 {
+    owner: string;
+    invariant: "one-plan-one-webgl-context";
+    allocations: readonly SceneBuilderAllocationDescriptorV1[];
+    byOwner: Readonly<Record<string, {
+        contextGlBytes: number;
+        preparationGlBytes: number;
+        cpuBytes: number;
+    }>>;
+    surfaceTextureBytes: number;
+    contextGlBytes: number;
+    preparationPeakGlBytes: number;
+    cpuBytes: number;
+    peakDeclaredLiveBytes: number;
+    budgetTriangles: number;
+    instantiatedTriangles: number;
+    exclusions: {
+        crossContextAndHostAggregation: "W7";
+        videoDecode: "W6" | "binding-owned";
+        browserProcess: "host-owned";
+        sourceBundles: "host-owned";
+        captureSession: "provider-owned";
+        driverAllocations: "excluded-unmeasured";
+        compositorSurfaces: "excluded-unmeasured";
+        decoderCaches: "excluded-unmeasured";
+    };
+}
+export interface SealedSceneShotPlanV1 {
+    version: 1;
+    status: "sealed";
+    sealSha256: string;
+    scene: SceneShotSpecV2;
+    output: ScenePlanOutputV1;
+    cameraIdentity: {
+        position: readonly [number, number, number];
+        fov: number;
+        near: number;
+        far: number;
+    };
+    motion: {
+        channels: SceneChannelV2[];
+        contentDurationInFrames: number;
+        finalContentFrame: number;
+        cameraClipPlanes: readonly {
+            near: number;
+            far: number;
+        }[];
+    };
+    objects: ScenePreparedObjectV1[];
+    surfaces: SceneSealedSurfaceV1[];
+    separation: SceneSeparationResultV2;
+    rigIdentity: ScenePreparedJson;
+    rigAllocations: readonly SceneBuilderAllocationDescriptorV1[];
+    fonts: readonly ScenePreparedFontFaceV1[];
+    ledger: ScenePlanAllocationLedgerV1;
+}
+export declare class ScenePreparedPlanRefusal extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/** Canonical allocation rows independently checked against the Three constructors by animate. */
+export declare function sceneW5PresetAllocationsV1(object: Extract<SceneObjectV2, {
+    kind: 'laptop' | 'phone' | 'page';
+}>): SceneBuilderAllocationDescriptorV1[];
+export declare function sceneW5WorldTextAllocationsV1(object: Extract<SceneObjectV2, {
+    kind: 'text';
+    space: 'world';
+}>, referenceWidth: number, outputWidth: number): SceneBuilderAllocationDescriptorV1[];
+export declare function sceneW5GeneratedRigAllocationsV1(edge: number, width: number, height: number): SceneBuilderAllocationDescriptorV1[];
+export declare const SCENE_CAPTURE_IDENTITY_FIELDS_V1: readonly ["componentId", "sourceVersionId", "params", "assetBindings", "layoutWidth", "layoutHeight", "bakeScale", "captureFrame", "durationInFrames", "fps", "seed", "brandFacts", "fontFacts", "mediaFacts", "rasterWidth", "rasterHeight", "runtimeIdentity", "dependencyIdentity", "browserProduct", "browserVersion", "browserExecutableSha256", "headless", "rasterAffectingFlags", "os", "arch", "deviceScaleFactor", "colorProfile", "requestedGlBackend", "actualGlBackend", "actualRenderer", "gpuIdentity"];
+/** Canonical portable JSON used for byte-stable plan hashing across Node and browser hosts. */
+export declare function canonicalScenePreparedJsonV1(value: unknown, path?: string): string;
+/** Strict top-level parser for the portable render boundary; nested authored scene uses its public V2 parser. */
+export declare function parseSealedSceneShotPlanV1(value: unknown): SealedSceneShotPlanV1;
+export declare function verifySealedSceneShotPlanV1(value: unknown, sha256: (canonical: string) => Promise<string>): Promise<SealedSceneShotPlanV1>;

package/dist/_members/composition/scene/resolution.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Report §5.6.2 — THE PROJECTED-RESOLUTION CHECK, and amendment A2's bake-scale selection.
+ *
+ * One rule doing three jobs, which is why it is written out exactly rather than left to a comment:
+ * it selects a 3× bake over the 2× default, it raises the refusal that A2 says must replace any
+ * silent reduction of quality, and it carries the lifecycle rule that says when it re-runs.
+ *
+ * Preparation owns selection and sealing. This portable pure module is shared by preparation and
+ * the runtime assertion so their projection arithmetic cannot drift:
+ *
+ *   - call `selectSceneBakeScale` once at PREPARATION, over the sealed schedule's complete frame
+ *     enumeration (`f = 0 … D−1`), not per frame at render time;
+ *   - write `bakeScale`, `bakeScaleReason`, `rasterWidth/Height` and `resolutionCheck` into the
+ *     sealed surface (report §5.9's `SealedSurface`), and let the render lane READ them;
+ *   - keep this module's arithmetic — the render lane may not re-derive a seal, and the seal and
+ *     the runtime check disagreeing invisibly is the failure this note exists to prevent.
+ *
+ * **Revalidation.** Sealed against one output size. It re-runs on a change to output width/height,
+ * `referenceSize`, any camera channel, any transform on the slot's object or its ancestors, the
+ * slot's declared dimensions, `layout`, or `bakeScale`. Capture PIXELS survive a revalidation when
+ * the capture identity still matches — the camera is not a capture-identity input, so a camera-only
+ * change revalidates this check WITHOUT invalidating the capture (report §2.2, §2.3).
+ */
+import type { SceneCameraV2, SceneTransformV2, SceneVec3 } from './schema.js';
+/**
+ * **The bound: at least one source texel per output pixel, on both axes, at every frame.**
+ *
+ * 1.0 is the magnification boundary itself, so it needs no tuning: below it the renderer is
+ * inventing detail, which is the resampled-UI failure the bake exists to avoid. It is a chosen
+ * bound placed at a physical boundary, not a measured one.
+ */
+export declare const RESOLUTION_BOUND = 1;
+/** The bake scales first delivery admits. Every preset admits both (report §5.6). */
+export declare const ALLOWED_BAKE_SCALES: readonly (2 | 3)[];
+/** Amendment A2: the default is 2× declared layout pixels. */
+export declare const DEFAULT_BAKE_SCALE: 2;
+/** Production camera depth policy shared by preparation and the Three camera adapter. */
+export declare function sceneCameraPlanesV2(referenceHeight: number, fov: number, scale: number): {
+    near: number;
+    far: number;
+};
+export type SceneBakeScale = 2 | 3;
+export type SceneResolutionRefusalCode = 'scene_surface_resolution_insufficient' | 'scene_surface_behind_eye';
+/**
+ * A typed refusal carrying its path and everything a corrective needs.
+ *
+ * A corrective may only name a bake scale the CONTRACT allows. §4.5 records the version of this
+ * helper that suggested an unauthorable "1×"; the rule that replaced it is why `neededScale` is
+ * drawn from `ALLOWED_BAKE_SCALES` and is `null` rather than invented when none reaches the bound.
+ */
+export declare class SceneResolutionRefusal extends Error {
+    readonly code: SceneResolutionRefusalCode;
+    readonly path: string;
+    readonly detail: Record<string, unknown>;
+    constructor(code: SceneResolutionRefusalCode, message: string, path: string, detail: Record<string, unknown>);
+}
+/** The slot rectangle's own declared size, in reference px (report §5.6's descriptor). */
+export interface SceneSlotRect {
+    width: number;
+    height: number;
+}
+/** One evaluated frame's pose: the camera, and the transform chain OUTERMOST FIRST. */
+export interface SceneEvaluatedPose {
+    camera: SceneCameraV2;
+    chain: readonly SceneTransformV2[];
+    /** Builder-resolved tl,tr,br,bl attachment quad; required by authoritative preparation. */
+    projectionQuad?: readonly [SceneVec3, SceneVec3, SceneVec3, SceneVec3];
+}
+export interface SceneOutputSize {
+    width: number;
+    height: number;
+}
+/**
+ * One world point projected to OUTPUT pixels through the §5.3 camera; `null` at or behind the eye.
+ *
+ * The camera's rotation is orthonormal, so its inverse is the transpose applied to `world − eye`.
+ */
+export declare function projectToOutputPixels(world: readonly [number, number, number], camera: SceneCameraV2, output: SceneOutputSize, scale: number): [number, number] | null;
+export type ProjectedSlotEdges = {
+    behindEye: true;
+    corner: 'tl' | 'tr' | 'br' | 'bl';
+} | {
+    behindEye: false;
+    widthPx: number;
+    heightPx: number;
+    corners: Record<'tl' | 'tr' | 'br' | 'bl', [number, number]>;
+};
+/**
+ * The projected U and V EDGE LENGTHS of a slot rectangle, in output pixels, at one frame.
+ *
+ * **Edges, not areas.** An area ratio hides a one-axis stretch entirely, and a one-axis stretch is
+ * exactly what resamples a capture. Each axis is taken as the MEAN of the two opposite edges of the
+ * projected quad: exact under an affine projection and the correct first-order value under
+ * perspective. The shorter edge alone would over-refuse a strongly foreshortened slot and the
+ * longer alone would under-refuse it.
+ */
+export declare function projectedSlotEdges({ slot, chain, camera, output, referenceSize, projectionQuad, path, frame }: {
+    slot: SceneSlotRect;
+    chain: readonly SceneTransformV2[];
+    camera: SceneCameraV2;
+    output: SceneOutputSize;
+    referenceSize: SceneOutputSize;
+    projectionQuad?: readonly [SceneVec3, SceneVec3, SceneVec3, SceneVec3];
+    path?: string;
+    frame?: number;
+}): ProjectedSlotEdges;
+export interface SceneResolutionCheckArgs {
+    /** The authored layer id, for the refusal path. */
+    surfaceId: string;
+    /** The slot's friendly name, for the refusal path. */
+    slotName: string;
+    slot: SceneSlotRect;
+    /** The component's DECLARED layout, in layout px. `raster = layout · bakeScale`. */
+    layout: {
+        width: number;
+        height: number;
+    };
+    /** D: the content frame count of the sealed schedule. The enumeration is complete, not sampled. */
+    contentDuration: number;
+    output: SceneOutputSize;
+    referenceSize: SceneOutputSize;
+    /** The evaluated pose at content frame `f`. */
+    evaluate: (frame: number) => SceneEvaluatedPose;
+}
+export interface SceneResolutionWorst {
+    frame: number;
+    densityU: number;
+    densityV: number;
+    axis: 'U' | 'V';
+    widthPx: number;
+    heightPx: number;
+}
+export interface SceneResolutionResult {
+    raster: {
+        width: number;
+        height: number;
+    };
+    bakeScale: SceneBakeScale;
+    worstDensity: number;
+    worstAt: SceneResolutionWorst;
+    meetsBound: boolean;
+    bound: number;
+}
+/**
+ * The metric, over every content frame of the sealed schedule.
+ *
+ * ```
+ * densityU(f) = rasterWidth  / projectedSlotWidthPx(f)
+ * densityV(f) = rasterHeight / projectedSlotHeightPx(f)
+ * density(f)  = min(densityU(f), densityV(f))     <- the WORSE axis governs
+ * worst       = min over f in [0, D−1] of density(f)
+ * ```
+ *
+ * Both axes, because a slot seen edge-on is minified on one and magnified on the other, and it is
+ * the magnified axis that resamples the capture. The outgoing transition hold adds no frames: it
+ * repeats `D−1`, which is already in the set.
+ */
+export declare function checkSurfaceResolution(args: SceneResolutionCheckArgs & {
+    bakeScale: SceneBakeScale;
+}): SceneResolutionResult;
+export interface SceneBakeScaleSelection {
+    selected: SceneBakeScale;
+    /** Report §5.9's `bakeScaleReason`, so the seal records WHY and a consumer can verify it. */
+    reason: 'declared' | 'default-sufficient' | 'raised-by-resolution-check';
+    results: Record<SceneBakeScale, SceneResolutionResult>;
+}
+/**
+ * **Selection (amendment A2, adopted).** The SMALLEST allowed scale meeting the bound, starting at
+ * the 2× default. An explicitly declared scale that meets the bound is honoured; one that does not
+ * is a REFUSAL — the author's declaration is never silently raised, and quality is never silently
+ * reduced and never bought by disabling anti-aliasing.
+ *
+ * Both of A2's qualifications are part of the record and neither is contradicted here: the spike's
+ * 2.5 % glyph-edge difference and I0's 0.29 % bar-edge difference between 2× and 3× do **not**
+ * prove invisibility, and "twelve faces" is not a guaranteed capacity because materials and other
+ * allocations share the 256 MiB budget.
+ */
+export declare function selectSceneBakeScale(args: SceneResolutionCheckArgs, declared?: SceneBakeScale): SceneBakeScaleSelection;