luo-cccc/hyperframes-previs

HyperFrames Downstream Previs Adapter

Adapter version 0.4.0. Input STORYBOARD_PREVIS_ADAPTER_V1, JSON state validation SCOPED_STATE_V2; frame identity PREVIS_RENDER_CONTENT_V2. Compiles delivered master scripts from script-to-storyboard-prompts into editable, reviewable 3D previsualizations, keeping the original segment number, master script, and budget version unchanged. Three.js handles scene and action, HyperFrames exports frame by frame.

Getting Started

Read references/upstream-adapter.md first, locating the user's explicit upstream project, formal segment, valid master script version, and budget version. Read the actual body text, scene analysis, character/scene/prop assets, and text-based opening/closing states. Input can be a project file or a locatable session delivery; cannot require the upstream to produce a separate storyboard design table.

Inherit the confirmed aspect ratio, complete style, segment duration limit, calculated runtime, shot order, character height in centimeters, model version, spatial orientation, original dialogue, sound responsibilities, and reveal timing. Do not re-ask confirmed items, and do not adopt the old demo's 16:9 / 12 seconds as the project default. When render resolution and fps are not specified, select an even resolution suitable for the aspect ratio and 24 fps, recording these as previs technical parameters; do not alter the budget or add plot points as a result. Only ask for missing items that affect this specific adaptation.

Upstream management of the seven-step process and formal segment coverage continues. This adapter reads authoritative state and writes its own files into <project>/previs/<formal_id>/<prompt_version>/, without modifying upstream next_required, cursor, overrides, master script, or budget. When the user says only "continue", execute the upstream's current target. Only engage when the current request includes previs or previs delivery is explicitly selected. Within a single authorized previs request, read, build, check, and export can be performed consecutively.

Supports state 1.8/V3 for existing text deliveries and 1.9/V4 for JSON projects. JSON uses scripts/intake_storyboard.py for read-only extraction; freeform text/sessions are read and structured by the agent, using scripts/finalize_manual_intake.py to seal the authentic evidence, without auto-migrating or guessing old state. Normal progression of other segments does not auto-invalidate the target segment. Re-adapt when this segment's version, related assets, opening/closing, or the selected original text changes. If old version STATE_JSON intake lacks scope validation data, explicitly re-extract; do not silently upgrade.

Use the simplest geometry sufficient to check composition, blocking, occlusion, and timing. Stable color codes correspond to upstream characters; environments only preserve relevant spaces and landmarks. Use models with permission for detailed actions when needed. Separate picture, action, and camera responsibilities; do not promise that simplified previs can force downstream models to follow pixel-for-pixel.

Making and Editing

1. Receive and Map. Adopt the upstream formal_id, prompt_version, budget_version, asset IDs, shot IDs, and time ranges. Translate "shot size, camera position", "camera movement and subject", "composition", and "frame content" into geometric scale, camera, target, and absolute time samples. Mark unspecified coordinates as execution supplements, do not re-direct. All shot and action times are relative to the current formal segment's 0 second. One-shot-per-scene segments are not split into cuts.
2. Build a Unified Space. Use metric, Y-up, with a noted orientation. Set up the scene, stable character IDs, prop assignments, dynamic structures like doors/windows. Distinguish character shapes with explicit color codes; provide geometric scale, avoiding guessing proportions from visuals alone.
3. Create Deterministically Evaluable Animation. The pose, position, camera, and door state at any frame must be determined solely by t. Do not use cumulative displacement, unseeded random numbers, or previous frame state to drive exports. Animation assets must use AnimationMixer.setTime(t) or equivalent absolute sampling. The browser playback timer can only call the same renderAt(t).
4. Check and Adjust. Verify each shot against the master script, cut points, and opening/closing states. Use frame selection, timeline, free camera view, camera/FOV editing, and path keyframe editing. Templates preview only the current shot trajectory; do not change shot count or budget. Confirmed shots/blocking can be explicitly locked; partial undo reverts only the most recent retained modification for the corresponding target. If changes affect actual cinematographic facts, story, duration, dialogue, or reveals, return to upstream for revision; do not use templates to replace existing director intent. See Editing & Frame Feedback.
5. Check and Export. Perform data and source checks, proxy spatial spot checks, actual frame-by-frame export, and verify video specs, opening/closing, and cut points. Only check for framing.requiredActors if explicitly indicated; spatial warnings need visual confirmation; do not substitute programmatic warning-free status for media acceptance review. Annotations include actual PNGs, segment timecode, object IDs, coordinates, and sources. When sources change, mark them as expired; separate processed and accepted annotations.
6. Return Adaptation Results. Deliver clean video, source project, source map, verbatim copy of the original master script, reference material attributions, and actual inspection receipt. The upstream master script or existing model adaptation drafts continue to serve as prompt sources; do not replace them with short auto-generated template prompts. The receipt represents only the local previs check; final model submission and generation capabilities are still handled by the corresponding model adaptation.

Reusable Start Point

assets/starter/ is a runtime example, containing a review page, absolute time sampling, save/export. The corridor, characters, props, three shots, and door opening event are demo content; when receiving upstream input, replace geometry and actions with actual input, do not automatically carry over these story elements. In the absence of pictures, use color-coded placeholders based on valid text files, explicitly only verifying space and timing.

node <skill-dir>/scripts/create_project.mjs <project-dir>
python -X utf8 <skill-dir>/scripts/intake_storyboard.py --state <upstream state JSON> --budget <upstream budget JSON> --formal-id FORMAL_1 --out <project-dir>/upstream-intake.json
cd <project-dir>
npm install
npm run prepare-libs

After reading the full master script, first implement the actual assets, shots, and actions into scene.json and scene code, writing assetBindings, sourceAssetIds, and adaptationMap. Then run the following binding and checks; do not skip binding and let the project revert to the demo branch:

npm run bind-upstream
npm run validate
npm run studio

sourceAssetIds.scenes/props explicitly lists the asset IDs actually used in this segment, writing [] for none used. Characters specify LOOK/STATE version and height via assetBindings. Numeric checks, version checks, and dependency checks do not replace story, dialogue, or cinematography semantic verification.

studio.html for review, index.html for clean export. Click on a character to select an object, click on empty space to select a frame point. Single shot/keyframe saves should not carry other drafts; conflicts are explicitly flagged. Locks are enforced server-side; partial undo retains 100 history entries; reject overwrite on external conflict. Before capture, save or discard camera draft, switch to official camera, hide selection boxes, and align to video frame.

npm run lint
npm run spatial-check
npm run snapshot
npm run render
npm run handoff
npm run feedback
node scripts/bundle.mjs --project . --out <new delivery bundle directory outside project>

The above commands are defined in the template's package.json. Dependencies are pinned to verified HyperFrames 0.9.10 and Three.js 0.187.0. New environments can update, but first check current official API, then re-validate export; do not simply change version numbers.

See Scene Contract for field definitions, Upstream Adapter for sources/revisions, Editing & Frame Feedback for lock/undo/annotation/spatial checks. Read Render Runtime, Handoff Bundle, and Portable Bundle as needed. See Design Rationale for adopted and deferred external designs; do not treat external repositories as prerequisites for production.

Delivery Judgment

• Narrative actions are discernible; characters, camera, and props have continuity between shots. Perform actual checks for axis, occlusion, and clipping; if deliberately crossing the axis, explain which shot establishes orientation.
• The same moment yields the same state when reached via sequential playback, direct jump, or reverse-order jump; verify at least one non-sequential sampling, e.g., 8 → 2 → 8.
• Original dialogue and sound timing are fully preserved in mapping and receipt; explicitly note unchecked items for unsynthesized sound, unimplemented lip sync, or complex actions. Asset prompt delivered, image exists, image read, and model bound are recorded separately.
• Each formal segment is exported independently by default; multi-segment or cross-segment splicing requires explicit request, stored as offset mapping. File boundaries do not automatically become cuts; do not repeat events from prior segments, do not extend or round the budget; non-whole-frame tails must explicitly record source clock vs. output clock mapping.
• Export uses saved shot data. The first frame is fully loaded, with no black frames, missing resources, authoring UI elements accidentally in frame, or cut point artifacts.
• Export is staged and checked before publishing; on failure, retain the previous successful video. Locking, writing history, and annotations do not change the frame identity; only substantive camera/path/model/code changes invalidate old frame evidence. Review still requires four-item consistency. VERIFIED annotation only indicates user recorded independent evidence, does not replace final model media acceptance.
• Model generation reinterprets materials, limbs, and details. Clearly state "composition and action intent that must be preserved" and "performance and texture allowed to be naturalized"; do not promise pixel-level or bone-level control.
• The final report must state the actual completed scope and actual verified scope. When no character references are provided or no downstream model is run, do not describe colored-block characters as character consistency verification, nor describe previs output as final generated footage.