9.3
11 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.
11.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
(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.