9.3
67 Source Programs and Authored Timelines
animate/authoring adds source-addressable authoring metadata to immutable scene? values. It remains headless: compiling a program does not open a preview window or render a frame.
67.1 Named source blocks
syntax
(define-scene-program program-id #:initial initial-scene-expr block-expr ...)
Defines program-id as an immutable scene-program?. The
initial expression evaluates to a Scene; each scene-block receives the
prefix Scene built by the preceding block and returns a new Scene. Block IDs
must be distinct. The macro retains source locations for reload diagnostics
and preview navigation.
syntax
(scene-block block-id (input-id) (~optional (~seq #:assets (asset-path ...))) (~optional (~seq #:version version-datum)) body-expr ...+)
Declares one block within define-scene-program. The binding
input-id is the immutable prefix Scene. #:assets lists
source files that invalidate the block on reload, and #:version is a
literal author-controlled invalidation key. A scene-block is syntax,
not a standalone runtime constructor.
(define-scene-program derivative #:initial (scene-add (make-scene) (plain-text 'title "Derivative")) (scene-block setup (scene) (scene-wait scene 1)) (scene-block reveal (scene) #:version 'v1 (scene-play scene (fade-in 'title) #:duration 1)))
procedure
(make-scene-program id initial-builder blocks) → scene-program? id : symbol? initial-builder : (-> scene?) blocks : (listof scene-block-spec?)
Constructs a source program without macro source locations. Use it when the
program is generated as data; ordinary source files should prefer
define-scene-program.
procedure
(make-scene-block id builder [ #:source-location location #:source-fingerprint fingerprint #:assets assets #:version version]) → scene-block-spec? id : symbol? builder : (-> scene? scene?) location : (or/c #f source-location?) = #f fingerprint : (or/c #f bytes? string?) = #f assets : (listof path-string?) = '() version : any/c = #f
Constructs one program block. This lower-level form is useful for program
generators; normal source files should use the macro form above.
procedure
(compile-scene-program program [ #:generation generation]) → compiled-scene-program? program : scene-program? generation : exact-nonnegative-integer? = 0
Evaluates the initial builder and each block into an immutable compiled program.
No renderer, GUI, or file operation is involved.
procedure
(scene-program? value) → boolean?
value : any/c
Recognizes source programs.
procedure
(scene-block-spec? value) → boolean?
value : any/c
Recognizes declarative source blocks.
procedure
(compiled-scene-program? value) → boolean?
value : any/c
Recognizes compiled source programs.
procedure
(compiled-scene-program-scene compiled) → scene?
compiled : compiled-scene-program?
Returns the completed Scene produced by compiling the source program. The Scene
is immutable and can be sampled, rendered, or passed to another headless
authoring operation without opening the preview GUI.
procedure
(source-location? value) → boolean?
value : any/c
Recognizes retained source-location metadata.
Limitation: source-program builders are arbitrary procedures. They are safe for an in-memory preview, but persistent project caches and subprocess previewing need a module-backed project source or an explicit cache key.