Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: complete documented visual track packages

kashorin1bc03ee3ae5d
diff --git a/examples/talking-film-graph-check/main.svml b/examples/talking-film-graph-check/main.svml
index 07825b57..880326c8 100644
--- a/examples/talking-film-graph-check/main.svml
+++ b/examples/talking-film-graph-check/main.svml
@@ -10,6 +10,7 @@
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+ <import as="fonts" from="@narratage/fonts-open@1"/>
<import as="text" from="@narratage/text-track@1"/>
<import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
@@ -48,9 +49,12 @@
<caption-fine:Track id="captions" display={story.caption} correspondence={story.caption.correspondence}
map={timing.map} space={speech.space}
plan={cue-plan.plan} program={caption-program}/>
+ <fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
+ <text:Style id="title-style" recipe={studio.text.title} font={title-font}/>
<text:Track id="titles" space={speech.space}>
- <text:Item text="MEANING" during="full" frame={title-frame}
- appearance={studio.text.title}/>
+ <text:Area id="meaning" placement={title-frame} style={title-style} during="program">
+ MEANING
+ </text:Area>
</text:Track>
<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
diff --git a/examples/talking-film-graph-check/studio.svs b/examples/talking-film-graph-check/studio.svs
index 8bee8108..2b5813be 100644
--- a/examples/talking-film-graph-check/studio.svs
+++ b/examples/talking-film-graph-check/studio.svs
@@ -22,7 +22,7 @@
cue-enter: fade; cue-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
}
text.title {
- stack-order: 90; font: Inter;
+ stack-order: 90;
weight: 900; size: 64; align: center; fill: #FFFFFF; tracking: -1;
}
</sheet>
diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lock
index d5ba9f20..b00a8bda 100644
--- a/examples/talking-film-graph-check/svml.packages.lock
+++ b/examples/talking-film-graph-check/svml.packages.lock
@@ -1,6 +1,551 @@
{
"format": "svml.node-package-lock@1",
"artifacts": [
+ {
+ "name": "@fontsource-variable/archivo",
+ "version": "5.3.0",
+ "digest": "sha256:0796c28568653dd1e715f8ab13f92c68c1974e87ab53f3ab251b0d4d8b494ce3"
+ },
+ {
+ "name": "@fontsource-variable/bodoni-moda",
+ "version": "5.3.0",
+ "digest": "sha256:af217a0c9edc9f8c41e1a4dc8a2041809ef40e5f7ed7abac5214812db846fad4"
+ },
+ {
+ "name": "@fontsource-variable/cabin",
+ "version": "5.3.0",
+ "digest": "sha256:225e3db5a6244485fd06ae097d2ca20ed1d4ca9eb395391bac50d47d25be642a"
+ },
+ {
+ "name": "@fontsource-variable/caveat",
+ "version": "5.3.0",
+ "digest": "sha256:cdf6e2824a455218cce75422a7707e59f5b6e1ad35876428ee2dc4d068f29493"
+ },
+ {
+ "name": "@fontsource-variable/cinzel",
+ "version": "5.3.0",
+ "digest": "sha256:1b7f026c3ec4ec319c1c7a4cca7125b38520cdc414689e0daf897f5ab085f242"
+ },
+ {
+ "name": "@fontsource-variable/cormorant-garamond",
+ "version": "5.3.0",
+ "digest": "sha256:31ec552ad9d8f91491ec077118ae96cd01e23a42a649782da0218a402b78d043"
+ },
+ {
+ "name": "@fontsource-variable/crimson-pro",
+ "version": "5.3.0",
+ "digest": "sha256:4ae40c19011a2a13dd861a0fde72a0828eebe031e7703a185ea177d72421f7fe"
+ },
+ {
+ "name": "@fontsource-variable/dm-sans",
+ "version": "5.3.0",
+ "digest": "sha256:03f466f40ee90dde39f101ca11553af719ef8883c4b124c0ea85634e77487ac8"
+ },
+ {
+ "name": "@fontsource-variable/eb-garamond",
+ "version": "5.3.0",
+ "digest": "sha256:03aa1388dd460c886b1342e8cbf9eb9313c90e97459969d39f1dbe1ee5729428"
+ },
+ {
+ "name": "@fontsource-variable/figtree",
+ "version": "5.3.0",
+ "digest": "sha256:694a87df28b2ad7e9fdbab1ffa5198bad595740e3026159905af5cc1af327613"
+ },
+ {
+ "name": "@fontsource-variable/fira-code",
+ "version": "5.3.0",
+ "digest": "sha256:d8bfe176b9932bad28ad1b8198b50694edd17f8b787630d4f448ec0d9ace4149"
+ },
+ {
+ "name": "@fontsource-variable/fraunces",
+ "version": "5.3.0",
+ "digest": "sha256:dac41ebceb99adf018de9167ef6b03b8222b7bc3bd526f6d533df6083b502f09"
+ },
+ {
+ "name": "@fontsource-variable/fredoka",
+ "version": "5.3.0",
+ "digest": "sha256:fea0c282954326529986f54a740e7d31e1beffd04be215d51029852a0725ff7a"
+ },
+ {
+ "name": "@fontsource-variable/geist-mono",
+ "version": "5.3.0",
+ "digest": "sha256:882f6807dedf3cca496bba28b944f86bf7cc66c2aa5a87e07d408bf34a0c201b"
+ },
+ {
+ "name": "@fontsource-variable/geist",
+ "version": "5.3.0",
+ "digest": "sha256:c33524602e5843f539843469fd5a7dae8bb6fc03ba8bfdbd82261fe1143169ec"
+ },
+ {
+ "name": "@fontsource-variable/instrument-sans",
+ "version": "5.3.0",
+ "digest": "sha256:7ec5129927e99cb03fdc37b11b8b467bc5896ff31bc645fd3c90819dbe4f2045"
+ },
+ {
+ "name": "@fontsource-variable/inter",
+ "version": "5.3.0",
+ "digest": "sha256:89a89893c7e4325e230fc57cafe6f07b40c33ea020ba9402e63770a17232b7be"
+ },
+ {
+ "name": "@fontsource-variable/jetbrains-mono",
+ "version": "5.3.0",
+ "digest": "sha256:49d39073ea71f2ca0e323fd2ba3ca9073e3da36fd0dea11b88495333eaeea43a"
+ },
+ {
+ "name": "@fontsource-variable/josefin-sans",
+ "version": "5.3.0",
+ "digest": "sha256:00df24506a7366a7a1fcf82b10c0bbfd5b5337e02c232841e98d282131684bc9"
+ },
+ {
+ "name": "@fontsource-variable/jost",
+ "version": "5.3.0",
+ "digest": "sha256:70f89fec25ff8763d9e040783960202834899b1c6761bdcc83cdfc775a34de1d"
+ },
+ {
+ "name": "@fontsource-variable/league-spartan",
+ "version": "5.3.0",
+ "digest": "sha256:7576bd2cb324f16de10b35fa6167de160c6e56c9a60df095887173ae802611d4"
+ },
+ {
+ "name": "@fontsource-variable/lexend",
+ "version": "5.3.0",
+ "digest": "sha256:5f6d9a64fe7f927259654ae981056ed19a963583c130a78c5518dd367fcf04e3"
+ },
+ {
+ "name": "@fontsource-variable/libre-baskerville",
+ "version": "5.3.0",
+ "digest": "sha256:bd89f402ea6b85f64d4c1427e56abf2057bdc1abd2a43f3d7e32693e80b447ac"
+ },
+ {
+ "name": "@fontsource-variable/lora",
+ "version": "5.3.0",
+ "digest": "sha256:f3be92343cd925c324687d25752f083f049c65e65230b890843703059ffa5f58"
+ },
+ {
+ "name": "@fontsource-variable/manrope",
+ "version": "5.3.0",
+ "digest": "sha256:3a7500a3fc15c16fd47d4efffecc84c95a3abf69daf541d8b11daf17357d7a65"
+ },
+ {
+ "name": "@fontsource-variable/merriweather",
+ "version": "5.3.0",
+ "digest": "sha256:7835083efd9b17a4117f81a0f2f3bab6102266926a05474d30e4fd647a7b81ad"
+ },
+ {
+ "name": "@fontsource-variable/montserrat",
+ "version": "5.3.0",
+ "digest": "sha256:9094e73ab6d0f4f567f5a0535146b7170eaafe05b7032697552ed56d7d54e173"
+ },
+ {
+ "name": "@fontsource-variable/mulish",
+ "version": "5.3.0",
+ "digest": "sha256:d58a1ad68f7c45487423356a7ef36c0ec4e2d6e427f7b1dcb8a5c0037acb0cb7"
+ },
+ {
+ "name": "@fontsource-variable/newsreader",
+ "version": "5.3.0",
+ "digest": "sha256:8b553bc6d2104d60981fc3eee5061efe41969a2e4fe5e435321bac8f5002ce59"
+ },
+ {
+ "name": "@fontsource-variable/noto-emoji",
+ "version": "5.3.0",
+ "digest": "sha256:a932b9a3d655a731923afd4cc75170cd3e9b3674b502235ba44be17a701ca203"
+ },
+ {
+ "name": "@fontsource-variable/noto-naskh-arabic",
+ "version": "5.3.0",
+ "digest": "sha256:067035df054003765dfcd4a2e5129178f469502a7c90c3f5d49051f7afd665fb"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-arabic",
+ "version": "5.3.0",
+ "digest": "sha256:1f2ce625b338e10f09ba02b45aefd384e0d4a26be865b61ee69694f80b97b2f7"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-devanagari",
+ "version": "5.3.0",
+ "digest": "sha256:9f99f8c442c6c1d4e2414ffe8bd1919a055d5f4a90220554392eef0f382b60d2"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-hebrew",
+ "version": "5.3.0",
+ "digest": "sha256:531120f91c80f1bebd2ec1ecb6e3af3af7115471995b7adb18906870c8cfd188"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-hk",
+ "version": "5.3.0",
+ "digest": "sha256:9a429e3f7834c5d8a20ee9fab235fbf15694b3f5a8fb1cbb52946178446b9ffa"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-jp",
+ "version": "5.3.0",
+ "digest": "sha256:bccf038ebd11916f00e8de0b5b800f003c0c3e98399dc32f4016971e2fac7da0"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-kr",
+ "version": "5.3.0",
+ "digest": "sha256:ef4ac56c9a687b7f959e44933a04b2f3a20463edc76b8ea31a7563324204721f"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-sc",
+ "version": "5.3.0",
+ "digest": "sha256:a90728ab595c8d90a10a82d6abee007b4974ced6e0f7e5d464fa67442f73dbbd"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-tc",
+ "version": "5.3.0",
+ "digest": "sha256:37e63a813e70c346e6b6c89aa610752dc16b0833586dbf83e96de61ca677babe"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans-thai",
+ "version": "5.3.0",
+ "digest": "sha256:86e8f04cfa4c22a3b19f99ebee20c101b0f131e7bfcaeb58f0b3e644366b169a"
+ },
+ {
+ "name": "@fontsource-variable/noto-sans",
+ "version": "5.3.0",
+ "digest": "sha256:0d19f8c6fa129ad33447401dcbd64ef7e6c49982e6df65b49b720a9e4f50069d"
+ },
+ {
+ "name": "@fontsource-variable/noto-serif-jp",
+ "version": "5.3.0",
+ "digest": "sha256:37f80759079143c614ffb81c6c885430c66409f10ef419270a635323fa3f81a7"
+ },
+ {
+ "name": "@fontsource-variable/noto-serif-kr",
+ "version": "5.3.0",
+ "digest": "sha256:855a1346244f5313f37e6315720165fa6d92d1ee5aa50cbd51978fe3c782b92c"
+ },
+ {
+ "name": "@fontsource-variable/noto-serif-sc",
+ "version": "5.3.0",
+ "digest": "sha256:cb6c63ebbfe6e9dcc942f3b130f01c0cedb576516eee48cf3332f81748769f0f"
+ },
+ {
+ "name": "@fontsource-variable/noto-serif-tc",
+ "version": "5.3.0",
+ "digest": "sha256:beae4cd943093ef82e5209e28fb8c5f376965583c0fa230d346fd2436bdc80cc"
+ },
+ {
+ "name": "@fontsource-variable/nunito-sans",
+ "version": "5.3.0",
+ "digest": "sha256:840eba2c3ac43ff53f43b0da202d959005ad40a4bbffe592fe64198a085da57a"
+ },
+ {
+ "name": "@fontsource-variable/onest",
+ "version": "5.3.0",
+ "digest": "sha256:31835b47c0976813973d62426a8e4c17af47873df95782ee37fa7d3b9e403bb5"
+ },
+ {
+ "name": "@fontsource-variable/open-sans",
+ "version": "5.3.0",
+ "digest": "sha256:49dd61b03fcdb1c84448819974edf4738c1446461c69eefafb5caca486f35494"
+ },
+ {
+ "name": "@fontsource-variable/oswald",
+ "version": "5.3.0",
+ "digest": "sha256:5cd84a85ad052ffb721f3b6ee92ed29cb5526de7e299e6b954844f5190e8faf2"
+ },
+ {
+ "name": "@fontsource-variable/outfit",
+ "version": "5.3.0",
+ "digest": "sha256:3df511d4bd0d3ca88695d4259c00b9a01417360025bd0a3e8dacfbff50f3e5a3"
+ },
+ {
+ "name": "@fontsource-variable/playfair-display",
+ "version": "5.3.0",
+ "digest": "sha256:e46bee836bbfe084fa42571a6dced3ade14bfd8142ce201340fecfc7fd99d269"
+ },
+ {
+ "name": "@fontsource-variable/playpen-sans",
+ "version": "5.3.0",
+ "digest": "sha256:38c6f03495c79bc5632273a0d7fe73a2efe45b1c494e5dae6a546216ccbf50bc"
+ },
+ {
+ "name": "@fontsource-variable/plus-jakarta-sans",
+ "version": "5.3.0",
+ "digest": "sha256:dee784042480c00a42780ca6006aa58b3d6c749639c21cf742a034c05e9bfa67"
+ },
+ {
+ "name": "@fontsource-variable/quicksand",
+ "version": "5.3.0",
+ "digest": "sha256:18f8cf372bba1f04630a43c9d2688809fc58f500f3b0f1d813c7a5bf4f020a91"
+ },
+ {
+ "name": "@fontsource-variable/raleway",
+ "version": "5.3.0",
+ "digest": "sha256:75303c03592356b54b0749b6fcbcbb0bce63eac8c690fd97584c3316f40fac43"
+ },
+ {
+ "name": "@fontsource-variable/rethink-sans",
+ "version": "5.3.0",
+ "digest": "sha256:d96a3068fe14018b1ea398f2ffbcc617445e9e7ed3d87231a0c9fea4278a3b0d"
+ },
+ {
+ "name": "@fontsource-variable/roboto-condensed",
+ "version": "5.3.0",
+ "digest": "sha256:627e267312d43979096fc8413b6fb081625d166025cd088be1c2ee0b61fcab5c"
+ },
+ {
+ "name": "@fontsource-variable/roboto-mono",
+ "version": "5.3.0",
+ "digest": "sha256:6514cfdfe5c709b2b460c2230f71018ab3ca9029905d4ae492ddfed7bb9ba51e"
+ },
+ {
+ "name": "@fontsource-variable/roboto-slab",
+ "version": "5.3.0",
+ "digest": "sha256:0ecefb8756e7b92c02c66b9554dc5cfcd6bb43c64990adf1a8554c640375e16a"
+ },
+ {
+ "name": "@fontsource-variable/roboto",
+ "version": "5.3.0",
+ "digest": "sha256:d1983bcad42e0ab6602e8206642c5d3784ee608e25b89160a9a223d7c5a6624c"
+ },
+ {
+ "name": "@fontsource-variable/rubik",
+ "version": "5.3.0",
+ "digest": "sha256:b12fd0da57db2c5dc17aceb57a31342c686513f3b73a20623b4a42e2ced86e58"
+ },
+ {
+ "name": "@fontsource-variable/shantell-sans",
+ "version": "5.3.0",
+ "digest": "sha256:e080dcf441282e93136aff939954303270a44a409b7d63b9a3085eb5125b2650"
+ },
+ {
+ "name": "@fontsource-variable/sora",
+ "version": "5.3.0",
+ "digest": "sha256:d31911726e28a40b3ed66fac06e2766f278ce80d9bc71954cb4d72a16b3f3a89"
+ },
+ {
+ "name": "@fontsource-variable/source-serif-4",
+ "version": "5.3.0",
+ "digest": "sha256:cf02c81bdbaef8b806e33b7ae34ba8b23fefa780d91e8c2441d80e3a0fa3030a"
+ },
+ {
+ "name": "@fontsource-variable/space-grotesk",
+ "version": "5.3.0",
+ "digest": "sha256:0b220a333c3b7dab5e5df39db35d1324897a725d0729ca00d42bc971bf5d7497"
+ },
+ {
+ "name": "@fontsource-variable/unbounded",
+ "version": "5.3.0",
+ "digest": "sha256:3cf459fe9626cd028467ee2aeac662c8b1f2c38ad357cbb91e08a8f4c97c9ec1"
+ },
+ {
+ "name": "@fontsource-variable/urbanist",
+ "version": "5.3.0",
+ "digest": "sha256:4bb5962df1a45c63dd5f9e22baa971ec5049e5cd0945e8248258efc9472c08dd"
+ },
+ {
+ "name": "@fontsource-variable/vollkorn",
+ "version": "5.3.0",
+ "digest": "sha256:9316350eae8018d816e185bfeee83f02005f7cb3896295a8f601d1421c22ea34"
+ },
+ {
+ "name": "@fontsource-variable/work-sans",
+ "version": "5.3.0",
+ "digest": "sha256:0edd30280383b66ad85d502b04830739b1dee53cea9ea7eb506ddf7907daa252"
+ },
+ {
+ "name": "@fontsource/abril-fatface",
+ "version": "5.3.0",
+ "digest": "sha256:ec157bfc3af761804abaaa172e16aa6727cf0bf6ca2cbf87d41fc6df6cdcdfc0"
+ },
+ {
+ "name": "@fontsource/alfa-slab-one",
+ "version": "5.3.0",
+ "digest": "sha256:bed06b886680db4650faffe748c7af255a1eae699ed0630031fd22dc800c9d46"
+ },
+ {
+ "name": "@fontsource/anton",
+ "version": "5.3.0",
+ "digest": "sha256:96e4e1dc687995d1fdc8530d40fc22b5e3986ffcbae28e9732a697894aa69240"
+ },
+ {
+ "name": "@fontsource/architects-daughter",
+ "version": "5.3.0",
+ "digest": "sha256:358aaa18557081b1d586cab3a0a95fc33244b078e5f74cc6850a9b6165b2e292"
+ },
+ {
+ "name": "@fontsource/archivo-black",
+ "version": "5.3.0",
+ "digest": "sha256:dc508efa883840ef153e07323940462a492bec060cc350ae53e663ac8da4d73d"
+ },
+ {
+ "name": "@fontsource/bangers",
+ "version": "5.3.0",
+ "digest": "sha256:e73b813f63ba063bafe98198de235af8f92ffd022d59b8ebec618a7f1ca03674"
+ },
+ {
+ "name": "@fontsource/barlow-condensed",
+ "version": "5.3.0",
+ "digest": "sha256:7f3ddd038aadd7382e650904b3da589af30735ef0dc01607469328943a935b70"
+ },
+ {
+ "name": "@fontsource/barlow",
+ "version": "5.3.0",
+ "digest": "sha256:d70f1cbbb1d650147ea21bfbaa9cc49cf2e2090f9b2d3803a77d921b86fe57b4"
+ },
+ {
+ "name": "@fontsource/bebas-neue",
+ "version": "5.3.0",
+ "digest": "sha256:ec23dbda86e9c44278e7f032d800fa6c94b985c47c621b41fd0ff3c3bbe1844a"
+ },
+ {
+ "name": "@fontsource/black-ops-one",
+ "version": "5.3.0",
+ "digest": "sha256:d7fb77fe59dbf7fef687d99a112dbd3ccf28ef2f87a8c6d98f35288555c31929"
+ },
+ {
+ "name": "@fontsource/bungee",
+ "version": "5.3.0",
+ "digest": "sha256:dd8285d74c7e7bec6763147c7ef4aa608c6e124ba0cb6d91759111ff523a828d"
+ },
+ {
+ "name": "@fontsource/coming-soon",
+ "version": "5.3.0",
+ "digest": "sha256:cd9ec9fa4740c39c3d4572c554e1440c585b2b31186ddd0773c5bf039c71f6fc"
+ },
+ {
+ "name": "@fontsource/dm-serif-display",
+ "version": "5.3.0",
+ "digest": "sha256:f040b50cd2ae51ece04df6ce1aa1541a7996b367afeba0e8bfab53b2b4a56199"
+ },
+ {
+ "name": "@fontsource/fira-sans-condensed",
+ "version": "5.3.0",
+ "digest": "sha256:6f5e1ddd0aa79c032433cfb3323f371ea5d190a12841d7aa6f843ef4f838fb18"
+ },
+ {
+ "name": "@fontsource/gloock",
+ "version": "5.3.0",
+ "digest": "sha256:12744ba4f717ab70a8543ce5783b0990789a16065309cb771943aeb607c6220b"
+ },
+ {
+ "name": "@fontsource/handlee",
+ "version": "5.3.0",
+ "digest": "sha256:7fe2354cb89c412cf401c308826b16614924745b8bf630beb97d4515802038dc"
+ },
+ {
+ "name": "@fontsource/ibm-plex-mono",
+ "version": "5.3.0",
+ "digest": "sha256:e6f7e22e58f688a0d1513b9f9c547df5e62dffec04d23fcf1901fc6e034417f8"
+ },
+ {
+ "name": "@fontsource/instrument-serif",
+ "version": "5.3.0",
+ "digest": "sha256:daeaae3c808e28d72ee4b906dbd455cba59ca3a9bb6dddac5742e3edf2bad5f4"
+ },
+ {
+ "name": "@fontsource/kalam",
+ "version": "5.3.0",
+ "digest": "sha256:c6f32f2fef20ab0cd9459bc4b511c8b7d888f854b61cfb7103fb4f6e56cc6014"
+ },
+ {
+ "name": "@fontsource/kanit",
+ "version": "5.3.0",
+ "digest": "sha256:4f8f7013eebd54e818becb147de69fe3f28c0ecfaa1abf734fd9d0b1bd124a85"
+ },
+ {
+ "name": "@fontsource/lato",
+ "version": "5.3.0",
+ "digest": "sha256:047ac68fa9d983c65b79191f71ce8f07d9fd34884d0ed743eb5c3cc2a13a7c60"
+ },
+ {
+ "name": "@fontsource/lilita-one",
+ "version": "5.3.0",
+ "digest": "sha256:47e218fee8999d9e320eb9ac4568f3670c8a877d044f22c6f48de6bd3b1e9636"
+ },
+ {
+ "name": "@fontsource/liu-jian-mao-cao",
+ "version": "5.3.0",
+ "digest": "sha256:411179910e33e03d2fb60b621dea6fe930c30531388e4b7d66569ed7078b793a"
+ },
+ {
+ "name": "@fontsource/long-cang",
+ "version": "5.3.0",
+ "digest": "sha256:afc5cbd69c9cf8365b62538cb6596d74afcec91adf375019c3430f048118b4e8"
+ },
+ {
+ "name": "@fontsource/luckiest-guy",
+ "version": "5.3.0",
+ "digest": "sha256:fc4f77c4e7401747bae26a3f5c53a8b6661245078ae5d0f4393637edb06f93ea"
+ },
+ {
+ "name": "@fontsource/ma-shan-zheng",
+ "version": "5.3.0",
+ "digest": "sha256:c720e4fb1f60e22d1d1fd6a595df9299ed74ee5207151895f87f740bbec152d8"
+ },
+ {
+ "name": "@fontsource/pacifico",
+ "version": "5.3.0",
+ "digest": "sha256:fa4b3a17b0ab42aa24e85dcae63ce9b97651bd1d7a1b92a0481dec16935776fd"
+ },
+ {
+ "name": "@fontsource/patrick-hand",
+ "version": "5.3.0",
+ "digest": "sha256:48e67c2d58c2a60cf0ce3ee92040f1d4bf607339f1ede99d8f5e214dde725950"
+ },
+ {
+ "name": "@fontsource/permanent-marker",
+ "version": "5.3.0",
+ "digest": "sha256:5ee1261d1bacd1c7e2e7ad00b3be625c97f72069589015177f535cb1280695c1"
+ },
+ {
+ "name": "@fontsource/pinyon-script",
+ "version": "5.3.0",
+ "digest": "sha256:4969aa2f2cbfad263c46b13ae862e7b0baed08fbeb536d8b863a47d0d9408907"
+ },
+ {
+ "name": "@fontsource/poppins",
+ "version": "5.3.0",
+ "digest": "sha256:3f6cfcca8abee2eb9cdf774a5af4dc5776f56b6ecabcd88afc8124a87ce08b39"
+ },
+ {
+ "name": "@fontsource/righteous",
+ "version": "5.3.0",
+ "digest": "sha256:60b43879f5b9295e2e02773720779fda978565848e66e5337c2558b189a38370"
+ },
+ {
+ "name": "@fontsource/satisfy",
+ "version": "5.3.0",
+ "digest": "sha256:c7432078d788f7d4b6713e1581eb04efbd07c879b7f38d0d757210b0a956a52c"
+ },
+ {
+ "name": "@fontsource/shadows-into-light",
+ "version": "5.3.0",
+ "digest": "sha256:72224d6afc4c504a7f5e7534664da9be076b4c53a4b21d7b2b564088c409200d"
+ },
+ {
+ "name": "@fontsource/short-stack",
+ "version": "5.3.0",
+ "digest": "sha256:1075b3d7603869c9aa7ec77591eab9c0d3e57a780d3f5eddba824da44b8f224d"
+ },
+ {
+ "name": "@fontsource/space-mono",
+ "version": "5.3.0",
+ "digest": "sha256:f06bb46ce8780fdfac003e8939e621ae4ed5e4c76cce5825baa15e2170016071"
+ },
+ {
+ "name": "@fontsource/zcool-kuaile",
+ "version": "5.3.0",
+ "digest": "sha256:e3111dfac9b1d8d7ee35868b5dec116f198b3fa103be304a993ee9009335c7ec"
+ },
+ {
+ "name": "@fontsource/zcool-qingke-huangyou",
+ "version": "5.3.0",
+ "digest": "sha256:3cc512e44ada84dba0c380cb73964c639b3e82a61bf2c85c9faa9f29012596f1"
+ },
+ {
+ "name": "@fontsource/zcool-xiaowei",
+ "version": "5.3.0",
+ "digest": "sha256:91eb6287d3e1d92731e0487b8f73ed9779711c7099bd8e3da723edb6b6a55186"
+ },
+ {
+ "name": "@infolektuell/noto-color-emoji",
+ "version": "0.2.0",
+ "digest": "sha256:a39972f9d0c5f4281f1c8f3560065d12676238e9ba494a03d23c26e49b233ac8"
+ },
{
"name": "@narratage/artifact",
"version": "0.0.0-dev",
@@ -29,7 +574,7 @@
{
"name": "@narratage/composition",
"version": "0.0.0-dev",
- "digest": "sha256:3a08807cfdbd28ca332c46644a6d807004d23aff9b683d46fca08e92ecad2368"
+ "digest": "sha256:4ab93e7d5d75a928e5ccedf3be6b9ad3b4b933242d030ed7a54333ec12eab767"
},
{
"name": "@narratage/core",
@@ -49,7 +594,12 @@
{
"name": "@narratage/film",
"version": "0.0.0-dev",
- "digest": "sha256:f17a912d29b69f86c35becc31c50d2ef7d9421a7c7acdb53f68be35aabb84b78"
+ "digest": "sha256:d341b735cc06fcda04f26b1179fa1cd4194e68a5ad7582c64e45974e790921d7"
+ },
+ {
+ "name": "@narratage/fonts-open",
+ "version": "0.0.0-dev",
+ "digest": "sha256:9c612242a487f7fef3f31897aad039cc2c2e74a84769ae43b8d0743263ce34e8"
},
{
"name": "@narratage/generation",
@@ -64,22 +614,22 @@
{
"name": "@narratage/hyperframes",
"version": "0.0.0-dev",
- "digest": "sha256:93c7a9a5ca241784d10356593c0be1575df0a846a9ae263888646a2f57385a36"
+ "digest": "sha256:b68547819e4a770472c9e3de80c97b5f48ec3ec8082437629488b3bfb27d6cc6"
},
{
"name": "@narratage/media-pipeline",
"version": "0.0.0-dev",
- "digest": "sha256:dad3a50c6ca9b1f1c18b5d7906387be8645c903190357b0944cf8d7f08546824"
+ "digest": "sha256:cced98019e873180b82774135a29af4ac304711b713b9b39cab35e7a63e973bb"
},
{
"name": "@narratage/media-track",
"version": "0.0.0-dev",
- "digest": "sha256:f6a874bf30529539a9956e1965a04c564f65a128d9e96c39bb0cf2c12b164163"
+ "digest": "sha256:99676006bbc96880c650f5dd594b9ebaf81092be38b738d604642db02db053b7"
},
{
"name": "@narratage/media",
"version": "0.0.0-dev",
- "digest": "sha256:059c7ebefb816a9831e5ce22edb4c9737ee1548428aba1108b054bc967989cf3"
+ "digest": "sha256:4c8d75a0362f598328dfe6d49e467602905053ea78f20930ef649391b9d4d338"
},
{
"name": "@narratage/model-kit",
@@ -139,7 +689,7 @@
{
"name": "@narratage/spatial",
"version": "0.0.0-dev",
- "digest": "sha256:ed17712ab17d3714befe14ba5faa9324bf1d9aff624817415cf3199eb26c915a"
+ "digest": "sha256:739fc82c71d949d18dd8f22caff2202223cf7e973b56e220c8f5cecc6642519d"
},
{
"name": "@narratage/speech-alignment",
@@ -179,7 +729,7 @@
{
"name": "@narratage/text-track",
"version": "0.0.0-dev",
- "digest": "sha256:54b31088b141e2cbce6201314433ed3a048d6a4f3fd7b4d204dcfd64bf0fa52d"
+ "digest": "sha256:f90bfba219a3e7d7c87192e2d9e12af4e1d422ffaa1836d9a4dfc167f3fb6aa2"
},
{
"name": "@narratage/text",
@@ -194,7 +744,7 @@
{
"name": "@narratage/visual-ir",
"version": "0.0.0-dev",
- "digest": "sha256:fbf0af7778388d444c6098359cb5af8498c40c6cc386be10305e524c00366a1e"
+ "digest": "sha256:fd0dda66d436ccdb32dc652d214d4c49b0400d2c97b6555f2505bbd7802033c7"
},
{
"name": "@narratage/whisperx",
@@ -218,8 +768,8 @@
"name": "@narratage/caption",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:071c416e7db22ff4be9436f6abc67621ee1895a6f50313f3b6d2d53e6bf34e77",
- "closureDigest": "sha256:36879850299b9d44be9893443cbf0aad6ca7cf5f9c34e52b0f1086313b7a2f33"
+ "facetsDigest": "sha256:be555bb438d801023c8dd18c4c10844c2c5cd5e86c8140a2a9915f56548e81b9",
+ "closureDigest": "sha256:998bd5ccf48369f4bc5d11397b21195e3ea7c8b81241051104b5e1ff1d962449"
},
{
"specifier": "@narratage/caption-fine",
@@ -227,8 +777,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:b69e22b722cd997dde42023c51b32211e456e35a9ef9ba637ad925f3cb1e7a1c",
- "closureDigest": "sha256:b251ce56441ef56ff21dcb468f79d9c65865be921e62287e09e364a7e83d1b52"
+ "facetsDigest": "sha256:10c6020217a2ba1fd330cfc3efd258ffce8dc7d08040272b174f62b6e06544d8",
+ "closureDigest": "sha256:5bd28a1972e13dec9d6a27f2311a74d09b202eb09ac11d46d9d72200fec572f0"
},
{
"specifier": "@narratage/caption-gemini",
@@ -236,8 +786,8 @@
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:e0a2507fb60a673c7bb624261e4ef840ca10d4c484d9f9f82e1ef129ba1dbe0b",
- "closureDigest": "sha256:54cb664fd62afe3d7ec0c6ceecb53df4e25bfeb033702fc86d4045298e045c3c"
+ "facetsDigest": "sha256:ae19ba9b7a2a114c575606c5dfd317e1f0a5a9e18d57864d99d026ca3d5d788e",
+ "closureDigest": "sha256:80a1b41d7a743e1244f4d31582dc6efcbacfda4b074544768b350f267db47b71"
},
{
"specifier": "@narratage/composition",
@@ -245,8 +795,8 @@
"name": "@narratage/composition",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:e7fecbcebc9a7f20e8db6760ff69a9056735e7ed1f6454e12770af48700b41dc",
- "closureDigest": "sha256:911cb6188bd23cb63490673b1927d08ee0fcdbf7b6a236be5d24d94c57d6ae72"
+ "facetsDigest": "sha256:80746c3804cf9db932e578d2665947487d225114a679d0ac1c3236d257a24163",
+ "closureDigest": "sha256:a46b8c26832f6c4e23427474f31c29161abfb01a472bfaa5087726f4d11de0d3"
},
{
"specifier": "@narratage/estimate",
@@ -254,8 +804,8 @@
"name": "@narratage/estimate",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:5f4b2fc1016f1a2d4b7d7a065f7b0082164ddb7af7e17030036b21b05c984bb2",
- "closureDigest": "sha256:da7e7ffc106205ba28874399ed484db32063c00256ca6c2e57c6a948823c92cc"
+ "facetsDigest": "sha256:183e7a60e001481a1afe78550658848d50f9708623addc99cd39c580c6da26a4",
+ "closureDigest": "sha256:246476071aba35160b8dcc3efa10838769bf4c60d676a6c908a5a967fed18071"
},
{
"specifier": "@narratage/film",
@@ -263,8 +813,17 @@
"name": "@narratage/film",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:0b02cd7057b1778da0fc2949967913787feab879aa301a9453352b5c6c10d439",
- "closureDigest": "sha256:5311d9ae01b6ecb8fcaf49cb6a34175eebf2801b47806bbca9bd1707d2a7bcd2"
+ "facetsDigest": "sha256:f96e301c1fe675b63d860fcbd81f164d1cc6be87ed86f76f5b0b1c644d16491c",
+ "closureDigest": "sha256:d3bdcc024240d43222e07fdca0486da8f231993b56123f6a3464ce399a7e5cd2"
+ },
+ {
+ "specifier": "@narratage/fonts-open",
+ "package": {
+ "name": "@narratage/fonts-open",
+ "version": "0.0.0-dev"
+ },
+ "facetsDigest": "sha256:8dee336f07a430b4ad7090aff617d0e0dbfff2dcab239589918a01e0a43e5d5a",
+ "closureDigest": "sha256:80700032089bbcd42fbcd4dd01bb8b5faf7fc41d572b7b7fc5c83a8ed3671e3a"
},
{
"specifier": "@narratage/generation",
@@ -281,8 +840,8 @@
"name": "@narratage/hyperframes",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:ee88f89eb47a7c06a1df3523a15a8ced2b1acbaac78ff6cc297ef8234b807bbf",
- "closureDigest": "sha256:be5513a7d2ac203069a5b926d8661dec80574f4060a9c96ee874715faf7c7103"
+ "facetsDigest": "sha256:ae15dd4c8a196fca46b14c860289b63f724ebc4ab9d65a05da91d6b1990a9f74",
+ "closureDigest": "sha256:07243c3bf865d26f6d810c1ef2aa44a93572149a06ec1daf987c4aab9e5d3d4a"
},
{
"specifier": "@narratage/media",
@@ -290,8 +849,8 @@
"name": "@narratage/media",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:b365049728f4fd4eaa8cf93792697c89cf7871b1f333b1d4b5bef1113dcfb218",
- "closureDigest": "sha256:d8cbdc19dac06b36788e22c98e82deae4683b40739f77f05b026f261a1e48a7d"
+ "facetsDigest": "sha256:745395a89ebae80fcf39c2f7badf0ae958aa7b37fd805c6f4317fbaac8c6790c",
+ "closureDigest": "sha256:8a4dc9175a98ef6a6f4ba263aa3be73811ccbea8999e2d2d3df8c5a1de403b55"
},
{
"specifier": "@narratage/media-pipeline",
@@ -299,8 +858,8 @@
"name": "@narratage/media-pipeline",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:0ab71314be714a96b94a79ffdb541aebc6613f707b45a5a896285985628f93f2",
- "closureDigest": "sha256:eece5ab677d8946755def49fb433e88f80a60a15cfda9e0be10057e7868faec5"
+ "facetsDigest": "sha256:cfffa17261efc97428c5daaeae4caa173caa62c1266c87c1b5b40a2bd67d39e9",
+ "closureDigest": "sha256:40439e192b53891ac4a6d62fc4ef2e0211e10769fea61f192f5ed43da445e751"
},
{
"specifier": "@narratage/media-track",
@@ -308,8 +867,8 @@
"name": "@narratage/media-track",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:db4ee70c3b876853d007cbf0b31856fde7ae3cb4e4b77e3323540c6deb730757",
- "closureDigest": "sha256:f26ab1bc9987ac567a2f898c7a2e658bd32a855d89b5470b54058e6bdbb60c7a"
+ "facetsDigest": "sha256:a946fcf5f6d847b83f6abf5976fde534f4e23796178f229bcdb2e8292dea3718",
+ "closureDigest": "sha256:5db14f8dad7909f1205257219587aadf8a4aad13c12bad07215043aaef13f781"
},
{
"specifier": "@narratage/narrative",
@@ -335,8 +894,8 @@
"name": "@narratage/render-hyperframes",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:136723c3a4cc5fdd1bc64fc65b2362ff48ee9512a1a4567bc243591b6b5eaf44",
- "closureDigest": "sha256:2238ece63ae0c148594c8b346970d97f0e741fccd26faf0d39037ce1af0d9fa3"
+ "facetsDigest": "sha256:436799d94e63a5228b3565a7de9bd7eb0ff2f3bfc9a3dd54118ebe418a53b228",
+ "closureDigest": "sha256:fb6a3509e48e650926b905c16bf272322d57533eb54a0c647fc18f23c5247fba"
},
{
"specifier": "@narratage/run-text",
@@ -362,8 +921,8 @@
"name": "@narratage/seedance",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:15f48aee0a7176aa0daf74332b0d331752d5b0e0f0694ba1b58b95b4a0575c95",
- "closureDigest": "sha256:280e8fdfa3d1cfb0420b454ed88bcf75648348faa682ee897db87f84d65fd88a"
+ "facetsDigest": "sha256:11ac335eb46c3bc638483b8ab9fbd0efea8c81f857d057df20f83506cd55a39a",
+ "closureDigest": "sha256:ead0e246bedbb51c521d0d974f70b8be7653246e8eb8d112d685b6fb514ceb75"
},
{
"specifier": "@narratage/semantic-map",
@@ -371,8 +930,8 @@
"name": "@narratage/semantic-map",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:91e600a9b2e1f8764f743874c9cb3d7a37135ebe3d832428ce55b820a9baacd1",
- "closureDigest": "sha256:38a57ebc3fd9de38a1bdb5ae34b07234bf797337e641f1c2c889c6e672fa83d6"
+ "facetsDigest": "sha256:eb8c949aec537ea18e7d36dce39ca1abd71b1294de3665f0ccb9915a6cbc06c9",
+ "closureDigest": "sha256:93af3a66a1381c5cb0ce8e80802128cae02dc134c5d3d87da473407771a2f42e"
},
{
"specifier": "@narratage/spatial",
@@ -380,8 +939,8 @@
"name": "@narratage/spatial",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:d72520078836b2fb2d5956d246f05707d7da7f566e7fa6c69f13f67659d22266",
- "closureDigest": "sha256:2af38c47ef4d854c4117e7637e0b6167012d54a50aae73de8e96de0df543db28"
+ "facetsDigest": "sha256:732ac784a6f5a5c0f333229853e9cab02572cdbf058a2771a3f79858cbe60ecc",
+ "closureDigest": "sha256:c3e5202dacb671533d446f4303c904a357f320515f49ff9af48d32fc09aa4392"
},
{
"specifier": "@narratage/speech",
@@ -389,8 +948,8 @@
"name": "@narratage/speech",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:cde5bb74f05f98e093728c4d80d818adfa3f2fc3d000b6f47b16150c9d3bb953",
- "closureDigest": "sha256:925eb115b12d4cf17501862ff901b46e1cf3b79979795c20c738e7198cae16ce"
+ "facetsDigest": "sha256:b89a1068bc0e3ad6adaca5829d89d13cd807ee0fb253a06c3aec4e813281ccdb",
+ "closureDigest": "sha256:a711c3cf33859d2e46324f21bc70259dbe0b2ca6ca2dc82f54813be34031e392"
},
{
"specifier": "@narratage/speech-alignment",
@@ -398,8 +957,8 @@
"name": "@narratage/speech-alignment",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:78ec7602fd8b161e1b323e5680c758ef0c3765f2eeb93fafb9fd2408356d73dc",
- "closureDigest": "sha256:55f68ba65ddc1802cbc20e1f204bf3804cd5c3b50ab424666e6490d631c69157"
+ "facetsDigest": "sha256:c1af69250f950294d2ea61a69ae77ee0a02751ce654b7576ca2a65baf9712a4d",
+ "closureDigest": "sha256:e824610960a22adcf4803fc45f3bd9a871ce8c7525f0cfc51707550e02539cdb"
},
{
"specifier": "@narratage/speech-basis",
@@ -407,8 +966,8 @@
"name": "@narratage/speech-basis",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:65b67f0e22be29ade11cafcd59f956cb11e2a0b28ae6d2ae25b40194e237f941",
- "closureDigest": "sha256:b01d15af2279db1efdbda7daec6c63d17a11a67211fdbc192f25e3ce731d628a"
+ "facetsDigest": "sha256:f7f00e597c92e1d04e10620173b878e3fe8ac51549e9a9d0025a5230dd0bff41",
+ "closureDigest": "sha256:08ab95a0043ce2a3c234f042e683f5ff85e71f6b55fdfdffc8465f0179f993dd"
},
{
"specifier": "@narratage/speech-evidence",
@@ -416,8 +975,8 @@
"name": "@narratage/speech-evidence",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:c555f832f6246d57523fd6d6837f1a191667f6a8efedbaf41ee7108d94e93952",
- "closureDigest": "sha256:91debf95bc3f59504f6026fe37d195299c988699145630e5aa37966a328e26fb"
+ "facetsDigest": "sha256:841f9de1eb7a50fb55bdd806702e9cba93f842d49a04dd614a3946f4894f1c21",
+ "closureDigest": "sha256:4c1f1238b76c25a57ab0bcc22b2ac0416199eee4fa19a642bb70a195161675e3"
},
{
"specifier": "@narratage/speech-spine",
@@ -425,8 +984,8 @@
"name": "@narratage/speech-spine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:473a49c922d0caae73b1d3102f82b74baed609c0a6730d4f0909f7cad2b4e49a",
- "closureDigest": "sha256:350fc90323c26b69aad40cc4d34e08502e2f06259d3ffefca032bb6b287174b2"
+ "facetsDigest": "sha256:d3a95a021f0ae6df0fc26fa7349287caa7fe6bbbf4ae6572bb0b2518f6989a5e",
+ "closureDigest": "sha256:3c272efe939616bce728e9fbe22d0dbf140ba960e3a9e03679f436e3aff736a4"
},
{
"specifier": "@narratage/svs",
@@ -444,7 +1003,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:baed248cfe1d4ea0e6924201a62ae7a5409bba5e995fd4a4b37eeb5c0738a4a2",
- "closureDigest": "sha256:ca1540d21f4275e22c9c81eafdffe6103b4100519ec09419444a7aedcb25191a"
+ "closureDigest": "sha256:c10296a9a84c9bc6a33bf1115d9bf0136b9f42609ee6215da67aad4696feec4a"
},
{
"specifier": "@narratage/text-track",
@@ -452,8 +1011,8 @@
"name": "@narratage/text-track",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:9bb698436ebc871b4a3ffddd1608d84f8d618ebe2e2017933fd2d8a34e762424",
- "closureDigest": "sha256:b8fae0b60355fa49ec445d9cbed076c11269c94323f7eaf41f3dae21c6298cd5"
+ "facetsDigest": "sha256:28375e5b861fa4c3b3e7c4416593fdb2841d4510d0ee5d2442a7bdd269fd8aff",
+ "closureDigest": "sha256:02f3274bee6f79d07441d68832a4ba407f118098d87919e7aef36028eefbf98a"
},
{
"specifier": "@narratage/visual-ir",
@@ -462,7 +1021,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:a8d72579639a41123f5ac017e98781819012adc52d94a8116c5a072dc9e6fc05",
- "closureDigest": "sha256:63d591b669757e83663dbae933870ffb852a66e83f831dd21aae259be1eddac1"
+ "closureDigest": "sha256:fcce4c49f3f2a462df231299106570e03b829fed0b269f91858f94b0e27fef0c"
},
{
"specifier": "@narratage/whisperx",
@@ -470,9 +1029,9 @@
"name": "@narratage/whisperx",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:14922531807c6de8acb17c869731efdc487c1e8b61a878bf8d65154381b9b980",
- "closureDigest": "sha256:038e0a971ed6cec9e12a20ca5b491deaada98a92f3429f465a536791888a7c74"
+ "facetsDigest": "sha256:00a2e488be04c36b007f1f1adf4197fa00768efe4e7023e85f6dbfd5a5eefaf8",
+ "closureDigest": "sha256:358dbb1b93fd592a0b28cbe1037830f2cecbcf02276deb1f025fe435bd1e63ef"
}
],
- "digest": "sha256:81700cabd86f435dd16447efb7c48bb4db03490b8894801e03c512bdb99dc7e2"
+ "digest": "sha256:1277726789eccdc735e3a93ef91ceca0f64d8db04f5c83a44ad9cf115ecd9fe0"
}
diff --git a/package.json b/package.json
index de83c270..7ea91405 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
"@narratage/caption-fine": "workspace:*",
"@narratage/caption-gemini": "workspace:*",
"@narratage/composition": "workspace:*",
+ "@narratage/deck-track": "workspace:*",
"@narratage/estimate": "workspace:*",
"@narratage/film": "workspace:*",
"@narratage/fonts-open": "workspace:*",
@@ -40,6 +41,7 @@
"@narratage/narrative": "workspace:*",
"@narratage/program-space": "workspace:*",
"@narratage/prompt-kit": "workspace:*",
+ "@narratage/ranking": "workspace:*",
"@narratage/provider-google-vertex": "workspace:*",
"@narratage/provider-hyperframes-local": "workspace:*",
"@narratage/provider-image-opencv-local": "workspace:*",
diff --git a/packages/composition/src/index.ts b/packages/composition/src/index.ts
index faf49bca..e1c1845f 100644
--- a/packages/composition/src/index.ts
+++ b/packages/composition/src/index.ts
@@ -1,5 +1,16 @@
export { compositionComponent } from "./component.js";
export { compositionDependency, compositionManifest, compositionManifestDigest, compositionModuleRef, compositionTypes, compositionValidatorDigests } from "./manifest.js";
-export { audioTrackSchema, compositionSchema, visualTrackSchema } from "./schema.js";
+export {
+ audioTrackSchema,
+ compositionSchema,
+ visualColorPaintSchema,
+ visualPathCommandSchema,
+ visualTextDocumentSchema,
+ visualTextFlowSchema,
+ visualTextPaintSchema,
+ visualTextSequenceSchema,
+ visualTextTypographySchema,
+ visualTrackSchema,
+} from "./schema.js";
export { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealAudioTrack, sealComposition, sealVisualTrack } from "./track.js";
export type * from "./track.js";
diff --git a/packages/composition/src/schema.ts b/packages/composition/src/schema.ts
index c629494a..7a32f2af 100644
--- a/packages/composition/src/schema.ts
+++ b/packages/composition/src/schema.ts
@@ -5,7 +5,10 @@ import { VISUAL_IR_V1, VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from
export { mediaDependency, programSpaceDependency };
const string = { kind: "string", minLength: 1 } as const; const number = { kind: "number", minimum: 0 } as const;
const integer = { kind: "number", integer: true, minimum: 0 } as const; const signedInteger = { kind: "number", integer: true } as const;
-const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const object = (
+ fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
+ allowUnknown = false,
+): ValueSchema => ({ kind: "object", fields, ...(allowUnknown ? { allowUnknown: true } : {}) });
const audioBlobRef = object({
kind: { schema: { kind: "literal", value: "blob" } },
digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
@@ -39,10 +42,131 @@ const keyframe = object({ atFrame: { schema: integer }, easing: { schema: { kind
const animation = object({ keyframes: { schema: { kind: "array", minItems: 2, items: keyframe } } });
const base = { id: { schema: string }, parent: { schema: string, optional: true }, order: { schema: integer }, style: { schema: { kind: "array", items: styleDeclaration } }, attributes: { schema: { kind: "array", items: attribute }, optional: true }, animation: { schema: animation, optional: true } } as const;
const box = object({ ...base, kind: { schema: { kind: "literal", value: "box" } } });
+const mask = object({
+ ...base,
+ kind: { schema: { kind: "literal", value: "mask" } },
+ mode: { schema: { kind: "string", enum: ["alpha", "luminance"] } },
+ maskElement: { schema: string },
+ contentElement: { schema: string },
+});
const text = object({ ...base, kind: { schema: { kind: "literal", value: "text" } }, text: { schema: { kind: "string" } }, fonts: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema }, optional: true } });
+const finiteNumber = { kind: "number" } as const;
+const boolean = { kind: "boolean" } as const;
+const enumString = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
+export const visualColorPaintSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "solid" } }, color: { schema: string } }),
+ object({
+ kind: { schema: { kind: "literal", value: "linear-gradient" } }, angleDeg: { schema: finiteNumber },
+ stops: { schema: { kind: "array", minItems: 2, items: object({ offset: { schema: finiteNumber }, color: { schema: string }, opacity: { schema: finiteNumber } }) } },
+ }),
+ object({
+ kind: { schema: { kind: "literal", value: "radial-gradient" } },
+ center: { schema: object({ x: { schema: finiteNumber }, y: { schema: finiteNumber } }) },
+ stops: { schema: { kind: "array", minItems: 2, items: object({ offset: { schema: finiteNumber }, color: { schema: string }, opacity: { schema: finiteNumber } }) } },
+ }),
+] };
+const textShadow = object({
+ paint: { schema: visualColorPaintSchema }, offsetX: { schema: finiteNumber }, offsetY: { schema: finiteNumber },
+ blurPx: { schema: number }, spreadPx: { schema: finiteNumber },
+});
+const boxDecoration = object({
+ fill: { schema: visualColorPaintSchema, optional: true },
+ border: { schema: object({
+ paint: { schema: visualColorPaintSchema },
+ widthsPx: { schema: object({ top: { schema: number }, right: { schema: number }, bottom: { schema: number }, left: { schema: number } }) },
+ style: { schema: enumString(["solid", "dashed", "dotted"]) },
+ }), optional: true },
+ paddingPx: { schema: object({ top: { schema: number }, right: { schema: number }, bottom: { schema: number }, left: { schema: number } }) },
+ radiiPx: { schema: object({ topLeft: { schema: number }, topRight: { schema: number }, bottomRight: { schema: number }, bottomLeft: { schema: number } }) },
+ shadows: { schema: { kind: "array", items: textShadow } },
+ tail: { schema: object({
+ side: { schema: enumString(["top", "right", "bottom", "left"]) }, offset: { schema: finiteNumber },
+ widthPx: { schema: number }, heightPx: { schema: number }, paint: { schema: visualColorPaintSchema },
+ }), optional: true },
+});
+export const visualTextPaintSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "fill" } }, paint: { schema: visualColorPaintSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "stroke" } }, paint: { schema: visualColorPaintSchema }, widthPx: { schema: number }, placement: { schema: enumString(["inside", "center", "outside"]) } }),
+ object({ kind: { schema: { kind: "literal", value: "shadow" } }, paint: { schema: visualColorPaintSchema }, offsetX: { schema: finiteNumber }, offsetY: { schema: finiteNumber }, blurPx: { schema: number }, spreadPx: { schema: finiteNumber } }),
+ object({ kind: { schema: { kind: "literal", value: "glow" } }, paint: { schema: visualColorPaintSchema }, blurPx: { schema: number }, spreadPx: { schema: finiteNumber } }),
+ object({ kind: { schema: { kind: "literal", value: "box" } }, target: { schema: enumString(["frame", "content", "paragraph", "line", "run", "word", "grapheme"]) }, continuity: { schema: enumString(["isolated", "joined"]) }, decoration: { schema: boxDecoration } }),
+] };
+const axis = object({ tag: { schema: { kind: "string", minLength: 4, maxLength: 4 } }, value: { schema: finiteNumber } });
+const feature = object({ tag: { schema: { kind: "string", minLength: 4, maxLength: 4 } }, enabled: { schema: boolean } });
+const textTypographyFields = {
+ fonts: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema } as ValueSchema, optional: true },
+ prototypeFamily: { schema: string, optional: true }, sizePx: { schema: { kind: "number", minimum: 0.000001 }, optional: false },
+ weight: { schema: { kind: "number", integer: true, minimum: 1, maximum: 1000 }, optional: false },
+ style: { schema: enumString(["normal", "italic", "oblique"]), optional: false },
+ axes: { schema: { kind: "array", items: axis } as ValueSchema, optional: false },
+ features: { schema: { kind: "array", items: feature } as ValueSchema, optional: false },
+ synthesis: { schema: enumString(["none", "weight", "style", "weight-style"]), optional: false },
+ kerning: { schema: enumString(["auto", "normal", "none"]), optional: false },
+ trackingPx: { schema: finiteNumber, optional: false }, wordSpacingPx: { schema: finiteNumber, optional: false },
+ lineHeight: { schema: { kind: "number", minimum: 0.000001 }, optional: false },
+ language: { schema: string, optional: true },
+ direction: { schema: enumString(["auto", "ltr", "rtl"]), optional: false },
+ writingMode: { schema: enumString(["horizontal-tb", "vertical-rl", "vertical-lr"]), optional: false },
+ baselineShiftPx: { schema: finiteNumber, optional: false }, tabSize: { schema: positiveInteger, optional: false },
+ indentationPx: { schema: finiteNumber, optional: false }, paragraphBeforePx: { schema: finiteNumber, optional: false },
+ paragraphAfterPx: { schema: finiteNumber, optional: false },
+ transform: { schema: enumString(["none", "uppercase", "lowercase", "capitalize"]), optional: false },
+ variantCaps: { schema: enumString(["normal", "small-caps", "all-small-caps"]), optional: false },
+ verticalAlign: { schema: enumString(["baseline", "super", "sub"]), optional: false },
+ decorations: { schema: { kind: "array", items: object({
+ line: { schema: enumString(["underline", "overline", "line-through"]) },
+ paint: { schema: visualColorPaintSchema },
+ style: { schema: enumString(["solid", "double", "dotted", "dashed", "wavy"]) },
+ thicknessPx: { schema: number, optional: true },
+ offsetPx: { schema: finiteNumber, optional: true },
+ skipInk: { schema: boolean },
+ }) } as ValueSchema, optional: false },
+ cjk: { schema: object({ textSpacing: { schema: enumString(["normal", "none"]) }, punctuationTrim: { schema: enumString(["none", "start", "end", "adjacent", "all"]) } }), optional: false },
+} as const;
+export const visualTextTypographySchema = object(textTypographyFields);
+const runTypography = object(Object.fromEntries(Object.entries(textTypographyFields).map(([name, field]) => [name, { schema: field.schema, optional: true }])));
+const runStyle = object({ typography: { schema: runTypography, optional: true }, paints: { schema: { kind: "array", items: visualTextPaintSchema }, optional: true } });
+const textInline: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "text" } }, id: { schema: string }, text: { schema: { kind: "string", minLength: 1 } }, style: { schema: runStyle, optional: true }, language: { schema: string, optional: true }, direction: { schema: enumString(["auto", "ltr", "rtl"]), optional: true } }),
+ object({ kind: { schema: { kind: "literal", value: "break" } }, id: { schema: string } }),
+] };
+export const visualTextDocumentSchema = object({ paragraphs: { schema: { kind: "array", minItems: 1, items: object({ id: { schema: string }, inlines: { schema: { kind: "array", minItems: 1, items: textInline } }, style: { schema: runStyle, optional: true } }) } } });
+export const visualTextFlowSchema = object({
+ form: { schema: { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "point" } }, anchorInline: { schema: enumString(["start", "center", "end"]) }, anchorBlock: { schema: enumString(["start", "center", "end"]) } }),
+ object({ kind: { schema: { kind: "literal", value: "area" } } }),
+ ] } },
+ inlineSize: { schema: enumString(["hug", "fixed"]) }, blockSize: { schema: enumString(["hug", "fixed"]) },
+ paddingPx: { schema: object({ inlineStart: { schema: number }, inlineEnd: { schema: number }, blockStart: { schema: number }, blockEnd: { schema: number } }) },
+ inlineAlign: { schema: enumString(["start", "center", "end", "justify"]) }, blockAlign: { schema: enumString(["start", "center", "end"]) },
+ wrap: { schema: enumString(["none", "word", "grapheme"]) }, overflow: { schema: enumString(["visible", "clip", "ellipsis", "shrink"]) },
+ maxLines: { schema: positiveInteger, optional: true }, minimumScale: { schema: { kind: "number", minimum: 0.000001, maximum: 1 }, optional: true },
+ clipToFrame: { schema: boolean }, columns: { schema: positiveInteger }, columnGapPx: { schema: number },
+ metricEdge: { schema: enumString(["line-box", "cap-height", "ink"]) },
+});
+export const visualTextSequenceSchema = object({
+ id: { schema: string }, unit: { schema: enumString(["paragraph", "line", "run", "word", "grapheme"]) },
+ range: { schema: object({ start: { schema: integer }, endExclusive: { schema: positiveInteger } }) },
+ order: { schema: enumString(["forward", "reverse", "random"]) }, startFrame: { schema: integer },
+ unitDurationFrames: { schema: positiveInteger }, staggerFrames: { schema: integer }, cycles: { schema: positiveInteger },
+ seed: { schema: signedInteger, optional: true },
+ keyframes: { schema: { kind: "array", minItems: 2, items: object({
+ atProgress: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true },
+ style: { schema: { kind: "array", minItems: 1, items: styleDeclaration } },
+ }) } },
+});
+const textFlowElement = object({ ...base, kind: { schema: { kind: "literal", value: "text-flow" } }, document: { schema: visualTextDocumentSchema }, typography: { schema: visualTextTypographySchema }, paints: { schema: { kind: "array", items: visualTextPaintSchema } }, flow: { schema: visualTextFlowSchema }, sequences: { schema: { kind: "array", items: visualTextSequenceSchema } } });
+export const visualPathCommandSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: enumString(["move", "line"]) }, x: { schema: finiteNumber }, y: { schema: finiteNumber } }),
+ object({ kind: { schema: { kind: "literal", value: "quadratic" } }, controlX: { schema: finiteNumber }, controlY: { schema: finiteNumber }, x: { schema: finiteNumber }, y: { schema: finiteNumber } }),
+ object({ kind: { schema: { kind: "literal", value: "cubic" } }, control1X: { schema: finiteNumber }, control1Y: { schema: finiteNumber }, control2X: { schema: finiteNumber }, control2Y: { schema: finiteNumber }, x: { schema: finiteNumber }, y: { schema: finiteNumber } }),
+ object({ kind: { schema: { kind: "literal", value: "close" } } }),
+] };
+const pathTextElement = object({ ...base, kind: { schema: { kind: "literal", value: "path-text" } }, document: { schema: visualTextDocumentSchema }, typography: { schema: visualTextTypographySchema }, paints: { schema: { kind: "array", items: visualTextPaintSchema } }, path: { schema: { kind: "array", minItems: 2, items: visualPathCommandSchema } }, side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) }, startMarginPx: { schema: number }, endMarginPx: { schema: number }, align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: boolean }, overflow: { schema: enumString(["visible", "clip"]) }, sequences: { schema: { kind: "array", items: visualTextSequenceSchema } }, marginAnimation: { schema: object({ keyframes: { schema: { kind: "array", minItems: 2, items: object({ atFrame: { schema: integer }, startMarginPx: { schema: number }, easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true } }) } } }), optional: true } });
const media = (kind: "image" | "video") => object({ ...base, kind: { schema: { kind: "literal", value: kind } }, artifact: { schema: mediaBlobRef }, sampling: { schema: sampling, optional: true }, mediaStartSec: { schema: number, optional: true }, playbackRate: { schema: number, optional: true }, loop: { schema: { kind: "boolean" }, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
const surface = object({ ...base, kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, sampling: { schema: sampling, optional: true } });
-const element: ValueSchema = { kind: "oneOf", variants: [box, text, media("image"), media("video"), surface] };
+const element: ValueSchema = { kind: "oneOf", variants: [box, mask, text, textFlowElement, pathTextElement, media("image"), media("video"), surface] };
const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
const present = object({ id: { schema: string }, span: { schema: span }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: element } } });
export const visualTrackSchema: ValueSchema = object({ contract: { schema: { kind: "literal", value: "svml.visual-track@1" } }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });
diff --git a/packages/composition/src/track.ts b/packages/composition/src/track.ts
index 5b9b98b5..52883e62 100644
--- a/packages/composition/src/track.ts
+++ b/packages/composition/src/track.ts
@@ -47,7 +47,7 @@ export type VisualAnimation = {
readonly keyframes: readonly VisualKeyframe[];
};
-type VisualElementBase = {
+export type VisualElementBase = {
readonly id: string;
readonly parent?: string;
readonly order: number;
@@ -60,6 +60,14 @@ export type VisualBoxElement = VisualElementBase & {
readonly kind: "box";
};
+/** A strictly local two-input mask. Both roots are direct owned children in the same Present. */
+export type VisualMaskElement = VisualElementBase & {
+ readonly kind: "mask";
+ readonly mode: "alpha" | "luminance";
+ readonly maskElement: string;
+ readonly contentElement: string;
+};
+
export type VisualTextElement = VisualElementBase & {
readonly kind: "text";
readonly text: string;
@@ -67,6 +75,219 @@ export type VisualTextElement = VisualElementBase & {
readonly fonts?: readonly FontArtifactRef[];
};
+export type VisualTextDirection = "auto" | "ltr" | "rtl";
+export type VisualTextWritingMode = "horizontal-tb" | "vertical-rl" | "vertical-lr";
+
+export type VisualTextTypography = {
+ /** Exact ordered faces. A renderer-family name is allowed only on the explicit prototype path. */
+ readonly fonts?: readonly FontArtifactRef[];
+ readonly prototypeFamily?: string;
+ readonly sizePx: number;
+ readonly weight: number;
+ readonly style: "normal" | "italic" | "oblique";
+ readonly axes: readonly { readonly tag: string; readonly value: number }[];
+ readonly features: readonly { readonly tag: string; readonly enabled: boolean }[];
+ readonly synthesis: "none" | "weight" | "style" | "weight-style";
+ readonly kerning: "auto" | "normal" | "none";
+ readonly trackingPx: number;
+ readonly wordSpacingPx: number;
+ readonly lineHeight: number;
+ readonly language?: string;
+ readonly direction: VisualTextDirection;
+ readonly writingMode: VisualTextWritingMode;
+ readonly baselineShiftPx: number;
+ readonly tabSize: number;
+ readonly indentationPx: number;
+ readonly paragraphBeforePx: number;
+ readonly paragraphAfterPx: number;
+ readonly transform: "none" | "uppercase" | "lowercase" | "capitalize";
+ readonly variantCaps: "normal" | "small-caps" | "all-small-caps";
+ readonly verticalAlign: "baseline" | "super" | "sub";
+ readonly decorations: readonly VisualTextDecoration[];
+ readonly cjk: {
+ readonly textSpacing: "normal" | "none";
+ readonly punctuationTrim: "none" | "start" | "end" | "adjacent" | "all";
+ };
+};
+
+/** Explicit run override. Omitted properties inherit; authored text never changes. */
+export type VisualTextRunStyle = {
+ readonly typography?: Partial<VisualTextTypography>;
+ readonly paints?: readonly VisualTextPaintLayer[];
+};
+
+export type VisualTextInline =
+ | {
+ readonly kind: "text";
+ readonly id: string;
+ readonly text: string;
+ readonly style?: VisualTextRunStyle;
+ readonly language?: string;
+ readonly direction?: VisualTextDirection;
+ }
+ | { readonly kind: "break"; readonly id: string };
+
+export type VisualTextDocument = {
+ readonly paragraphs: readonly {
+ readonly id: string;
+ readonly inlines: readonly VisualTextInline[];
+ readonly style?: VisualTextRunStyle;
+ }[];
+};
+
+export type VisualColorPaint =
+ | { readonly kind: "solid"; readonly color: string }
+ | {
+ readonly kind: "linear-gradient";
+ readonly angleDeg: number;
+ readonly stops: readonly { readonly offset: number; readonly color: string; readonly opacity: number }[];
+ }
+ | {
+ readonly kind: "radial-gradient";
+ readonly center: { readonly x: number; readonly y: number };
+ readonly stops: readonly { readonly offset: number; readonly color: string; readonly opacity: number }[];
+ };
+
+export type VisualTextDecoration = {
+ readonly line: "underline" | "overline" | "line-through";
+ readonly paint: VisualColorPaint;
+ readonly style: "solid" | "double" | "dotted" | "dashed" | "wavy";
+ readonly thicknessPx?: number;
+ readonly offsetPx?: number;
+ readonly skipInk: boolean;
+};
+
+export type VisualTextBoxDecoration = {
+ readonly fill?: VisualColorPaint;
+ readonly border?: {
+ readonly paint: VisualColorPaint;
+ readonly widthsPx: { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number };
+ readonly style: "solid" | "dashed" | "dotted";
+ };
+ readonly paddingPx: { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number };
+ readonly radiiPx: { readonly topLeft: number; readonly topRight: number; readonly bottomRight: number; readonly bottomLeft: number };
+ readonly shadows: readonly {
+ readonly paint: VisualColorPaint;
+ readonly offsetX: number;
+ readonly offsetY: number;
+ readonly blurPx: number;
+ readonly spreadPx: number;
+ }[];
+ readonly tail?: {
+ readonly side: "top" | "right" | "bottom" | "left";
+ readonly offset: number;
+ readonly widthPx: number;
+ readonly heightPx: number;
+ readonly paint: VisualColorPaint;
+ };
+};
+
+export type VisualTextPaintTarget = "frame" | "content" | "paragraph" | "line" | "run" | "word" | "grapheme";
+
+/** Ordered renderer-neutral text Paint. Repetition and array order are semantic. */
+export type VisualTextPaintLayer =
+ | { readonly kind: "fill"; readonly paint: VisualColorPaint }
+ | {
+ readonly kind: "stroke";
+ readonly paint: VisualColorPaint;
+ readonly widthPx: number;
+ readonly placement: "inside" | "center" | "outside";
+ }
+ | {
+ readonly kind: "shadow";
+ readonly paint: VisualColorPaint;
+ readonly offsetX: number;
+ readonly offsetY: number;
+ readonly blurPx: number;
+ readonly spreadPx: number;
+ }
+ | { readonly kind: "glow"; readonly paint: VisualColorPaint; readonly blurPx: number; readonly spreadPx: number }
+ | {
+ readonly kind: "box";
+ readonly target: VisualTextPaintTarget;
+ readonly continuity: "isolated" | "joined";
+ readonly decoration: VisualTextBoxDecoration;
+ };
+
+export type VisualTextFlow = {
+ readonly form:
+ | {
+ readonly kind: "point";
+ readonly anchorInline: "start" | "center" | "end";
+ readonly anchorBlock: "start" | "center" | "end";
+ }
+ | { readonly kind: "area" };
+ readonly inlineSize: "hug" | "fixed";
+ readonly blockSize: "hug" | "fixed";
+ readonly paddingPx: { readonly inlineStart: number; readonly inlineEnd: number; readonly blockStart: number; readonly blockEnd: number };
+ readonly inlineAlign: "start" | "center" | "end" | "justify";
+ readonly blockAlign: "start" | "center" | "end";
+ readonly wrap: "none" | "word" | "grapheme";
+ readonly overflow: "visible" | "clip" | "ellipsis" | "shrink";
+ readonly maxLines?: number;
+ readonly minimumScale?: number;
+ readonly clipToFrame: boolean;
+ readonly columns: number;
+ readonly columnGapPx: number;
+ readonly metricEdge: "line-box" | "cap-height" | "ink";
+};
+
+export type VisualTextSequenceAnimation = {
+ readonly id: string;
+ readonly unit: "paragraph" | "line" | "run" | "word" | "grapheme";
+ readonly range: { readonly start: number; readonly endExclusive: number };
+ readonly order: "forward" | "reverse" | "random";
+ readonly startFrame: number;
+ readonly unitDurationFrames: number;
+ readonly staggerFrames: number;
+ readonly cycles: number;
+ readonly seed?: number;
+ readonly keyframes: readonly {
+ readonly atProgress: number;
+ readonly easing?: VisualEasing;
+ readonly style: readonly VisualStyleDeclaration[];
+ }[];
+};
+
+/** Exact terminal text flow. It contains no author Style/Recipe reference or renderer callback. */
+export type VisualTextFlowElement = VisualElementBase & {
+ readonly kind: "text-flow";
+ readonly document: VisualTextDocument;
+ readonly typography: VisualTextTypography;
+ readonly paints: readonly VisualTextPaintLayer[];
+ readonly flow: VisualTextFlow;
+ readonly sequences: readonly VisualTextSequenceAnimation[];
+};
+
+export type VisualVectorPathCommand =
+ | { readonly kind: "move" | "line"; readonly x: number; readonly y: number }
+ | { readonly kind: "quadratic"; readonly controlX: number; readonly controlY: number; readonly x: number; readonly y: number }
+ | { readonly kind: "cubic"; readonly control1X: number; readonly control1Y: number; readonly control2X: number; readonly control2Y: number; readonly x: number; readonly y: number }
+ | { readonly kind: "close" };
+
+export type VisualPathTextElement = VisualElementBase & {
+ readonly kind: "path-text";
+ readonly document: VisualTextDocument;
+ readonly typography: VisualTextTypography;
+ readonly paints: readonly VisualTextPaintLayer[];
+ readonly path: readonly VisualVectorPathCommand[];
+ readonly side: "left" | "right";
+ readonly orientation: "follow" | "upright";
+ readonly startMarginPx: number;
+ readonly endMarginPx: number;
+ readonly align: "start" | "center" | "end";
+ readonly reverse: boolean;
+ readonly overflow: "visible" | "clip";
+ readonly sequences: readonly VisualTextSequenceAnimation[];
+ readonly marginAnimation?: {
+ readonly keyframes: readonly {
+ readonly atFrame: number;
+ readonly startMarginPx: number;
+ readonly easing?: VisualEasing;
+ }[];
+ };
+};
+
export type VisualSamplingRational = {
readonly numerator: number;
readonly denominator: number;
@@ -116,7 +337,7 @@ export type VisualSurfaceElement = VisualElementBase & {
* Elements may reference only parents in the same Present. They have no selector,
* script, sibling Track id or accumulated-composite input.
*/
-export type VisualElement = VisualBoxElement | VisualTextElement | VisualMediaElement | VisualSurfaceElement;
+export type VisualElement = VisualBoxElement | VisualMaskElement | VisualTextElement | VisualTextFlowElement | VisualPathTextElement | VisualMediaElement | VisualSurfaceElement;
export type VisualPresent = {
readonly id: string;
@@ -190,6 +411,16 @@ const ANIMATABLE_LOCAL_STYLES = new Set([
"transform",
]);
+const ANIMATABLE_TEXT_UNIT_STYLES = new Set([
+ "-webkit-text-fill-color",
+ "-webkit-text-stroke-color",
+ "background-color",
+ "color",
+ "filter",
+ "opacity",
+ "transform",
+]);
+
function assertNonEmpty(value: string, label: string): void {
if (!value) throw new Error(`${label} must not be empty.`);
}
@@ -300,9 +531,15 @@ function assertStyle(style: readonly VisualStyleDeclaration[], label: string): v
function assertAttributes(attributes: readonly VisualAttribute[] | undefined, label: string): void {
const names = new Set<string>();
for (const attribute of attributes ?? []) {
- if (!/^(?:data-[a-z0-9-]+|aria-[a-z0-9-]+|role|title)$/u.test(attribute.name)) {
+ if (!/^(?:data-[a-z0-9-]+|aria-[a-z0-9-]+|role|title|lang|dir)$/u.test(attribute.name)) {
throw new Error(`${label} contains unsafe attribute ${attribute.name}.`);
}
+ if (attribute.name === "lang" && !/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u.test(attribute.value)) {
+ throw new Error(`${label} contains invalid lang ${attribute.value}.`);
+ }
+ if (attribute.name === "dir" && !["ltr", "rtl", "auto"].includes(attribute.value)) {
+ throw new Error(`${label} contains invalid dir ${attribute.value}.`);
+ }
if (names.has(attribute.name)) {
throw new Error(`${label} contains duplicate attribute ${attribute.name}.`);
}
@@ -310,6 +547,352 @@ function assertAttributes(attributes: readonly VisualAttribute[] | undefined, la
}
}
+function assertExactFonts(fonts: readonly FontArtifactRef[] | undefined, label: string): void {
+ if (fonts === undefined) return;
+ if (fonts.length === 0) throw new Error(`${label} has an empty font stack.`);
+ const faces = new Set<string>();
+ for (const [index, font] of fonts.entries()) {
+ assertFontArtifactRef(font, `${label}.${index}`);
+ const face = digestOf(font);
+ if (faces.has(face)) throw new Error(`${label} has a duplicate font face.`);
+ faces.add(face);
+ }
+}
+
+function finite(value: number, label: string): void {
+ if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
+}
+
+function nonNegative(value: number, label: string): void {
+ finite(value, label);
+ if (value < 0) throw new Error(`${label} must not be negative.`);
+}
+
+function assertColor(value: string, label: string): void {
+ assertNonEmpty(value, label);
+ if (value.length > 256
+ || /[;{}<>"'\\]|!important|[\u0000-\u001f\u007f]/iu.test(value)
+ || /(?:url|var|env|attr|image-set)\s*\(/iu.test(value)) {
+ throw new Error(`${label} contains an unsafe or environment-dependent color.`);
+ }
+}
+
+function assertColorPaint(paint: VisualColorPaint, label: string): void {
+ if (paint.kind === "solid") {
+ assertColor(paint.color, `${label}.color`);
+ return;
+ }
+ if (paint.kind !== "linear-gradient" && paint.kind !== "radial-gradient") {
+ throw new Error(`${label} has an unsupported Paint kind.`);
+ }
+ if (paint.kind === "linear-gradient") finite(paint.angleDeg, `${label}.angleDeg`);
+ else {
+ finite(paint.center.x, `${label}.center.x`);
+ finite(paint.center.y, `${label}.center.y`);
+ if (paint.center.x < 0 || paint.center.x > 1 || paint.center.y < 0 || paint.center.y > 1) {
+ throw new Error(`${label}.center must be normalized.`);
+ }
+ }
+ if (paint.stops.length < 2) throw new Error(`${label} requires at least two gradient stops.`);
+ let previous = -1;
+ for (const [index, stop] of paint.stops.entries()) {
+ finite(stop.offset, `${label}.stops.${index}.offset`);
+ finite(stop.opacity, `${label}.stops.${index}.opacity`);
+ assertColor(stop.color, `${label}.stops.${index}.color`);
+ if (stop.offset < 0 || stop.offset > 1 || stop.offset < previous || stop.opacity < 0 || stop.opacity > 1) {
+ throw new Error(`${label} has invalid gradient stops.`);
+ }
+ previous = stop.offset;
+ }
+}
+
+function assertTypography(typography: VisualTextTypography, label: string): void {
+ assertExactFonts(typography.fonts, `${label}.fonts`);
+ if (typography.fonts === undefined && !typography.prototypeFamily?.trim()) {
+ throw new Error(`${label} requires exact fonts or an explicit prototypeFamily.`);
+ }
+ if (typography.fonts !== undefined && typography.prototypeFamily !== undefined) {
+ throw new Error(`${label} cannot mix exact fonts with prototypeFamily.`);
+ }
+ finite(typography.sizePx, `${label}.sizePx`);
+ if (typography.sizePx <= 0 || !Number.isSafeInteger(typography.weight) || typography.weight < 1 || typography.weight > 1_000) {
+ throw new Error(`${label} size or weight is invalid.`);
+ }
+ if (!["normal", "italic", "oblique"].includes(typography.style)
+ || !["none", "weight", "style", "weight-style"].includes(typography.synthesis)
+ || !["auto", "normal", "none"].includes(typography.kerning)
+ || !["auto", "ltr", "rtl"].includes(typography.direction)
+ || !["horizontal-tb", "vertical-rl", "vertical-lr"].includes(typography.writingMode)
+ || !["none", "uppercase", "lowercase", "capitalize"].includes(typography.transform)
+ || !["normal", "small-caps", "all-small-caps"].includes(typography.variantCaps)
+ || !["baseline", "super", "sub"].includes(typography.verticalAlign)) {
+ throw new Error(`${label} contains an unsupported typography enum.`);
+ }
+ for (const [name, value] of Object.entries({
+ trackingPx: typography.trackingPx,
+ wordSpacingPx: typography.wordSpacingPx,
+ lineHeight: typography.lineHeight,
+ baselineShiftPx: typography.baselineShiftPx,
+ indentationPx: typography.indentationPx,
+ paragraphBeforePx: typography.paragraphBeforePx,
+ paragraphAfterPx: typography.paragraphAfterPx,
+ })) finite(value, `${label}.${name}`);
+ if (typography.lineHeight <= 0 || !Number.isSafeInteger(typography.tabSize) || typography.tabSize <= 0) {
+ throw new Error(`${label} lineHeight or tabSize is invalid.`);
+ }
+ const axes = new Set<string>();
+ for (const [index, axis] of typography.axes.entries()) {
+ if (!/^[\x20-\x7e]{4}$/u.test(axis.tag) || axes.has(axis.tag)) throw new Error(`${label}.axes.${index} is invalid.`);
+ finite(axis.value, `${label}.axes.${index}.value`);
+ axes.add(axis.tag);
+ }
+ const features = new Set<string>();
+ for (const [index, feature] of typography.features.entries()) {
+ if (!/^[\x20-\x7e]{4}$/u.test(feature.tag) || features.has(feature.tag)) throw new Error(`${label}.features.${index} is invalid.`);
+ features.add(feature.tag);
+ }
+ const decorations = new Set<string>();
+ for (const [index, decoration] of typography.decorations.entries()) {
+ const item = `${label}.decorations.${index}`;
+ if (!["underline", "overline", "line-through"].includes(decoration.line)
+ || !["solid", "double", "dotted", "dashed", "wavy"].includes(decoration.style)
+ || decorations.has(decoration.line)) {
+ throw new Error(`${item} is invalid or repeated.`);
+ }
+ decorations.add(decoration.line);
+ assertColorPaint(decoration.paint, `${item}.paint`);
+ if (decoration.thicknessPx !== undefined) nonNegative(decoration.thicknessPx, `${item}.thicknessPx`);
+ if (decoration.offsetPx !== undefined) finite(decoration.offsetPx, `${item}.offsetPx`);
+ }
+}
+
+function assertRunStyle(style: VisualTextRunStyle | undefined, label: string): void {
+ if (style === undefined) return;
+ if (style.typography !== undefined) {
+ const merged = style.typography;
+ if (merged.fonts !== undefined) assertExactFonts(merged.fonts, `${label}.fonts`);
+ for (const [name, value] of Object.entries(merged)) {
+ if (typeof value === "number") finite(value, `${label}.${name}`);
+ }
+ }
+ for (const [index, paint] of (style.paints ?? []).entries()) assertTextPaint(paint, `${label}.paints.${index}`);
+}
+
+function inheritedTypography(
+ base: VisualTextTypography,
+ style: VisualTextRunStyle | undefined,
+): VisualTextTypography {
+ const override = style?.typography;
+ if (override === undefined) return base;
+ const fontSelection = override.fonts !== undefined
+ ? { fonts: override.fonts }
+ : override.prototypeFamily !== undefined
+ ? { prototypeFamily: override.prototypeFamily }
+ : base.fonts === undefined
+ ? { prototypeFamily: base.prototypeFamily! }
+ : { fonts: base.fonts };
+ const {
+ fonts: _fonts,
+ prototypeFamily: _prototypeFamily,
+ axes: _axes,
+ features: _features,
+ decorations: _decorations,
+ cjk: _cjk,
+ ...scalarOverrides
+ } = override;
+ return {
+ ...base,
+ ...scalarOverrides,
+ ...fontSelection,
+ axes: override.axes ?? base.axes,
+ features: override.features ?? base.features,
+ decorations: override.decorations ?? base.decorations,
+ cjk: override.cjk === undefined ? base.cjk : { ...base.cjk, ...override.cjk },
+ };
+}
+
+function assertTextDocument(
+ document: VisualTextDocument,
+ typography: VisualTextTypography,
+ label: string,
+): void {
+ if (document.paragraphs.length === 0) throw new Error(`${label} has no paragraphs.`);
+ const ids = new Set<string>();
+ let hasText = false;
+ for (const [paragraphIndex, paragraph] of document.paragraphs.entries()) {
+ assertNonEmpty(paragraph.id, `${label}.paragraphs.${paragraphIndex}.id`);
+ if (ids.has(paragraph.id) || paragraph.inlines.length === 0) throw new Error(`${label} has an invalid paragraph.`);
+ ids.add(paragraph.id);
+ assertRunStyle(paragraph.style, `${label}.paragraphs.${paragraphIndex}.style`);
+ const paragraphTypography = inheritedTypography(typography, paragraph.style);
+ assertTypography(paragraphTypography, `${label}.paragraphs.${paragraphIndex}.typography`);
+ for (const [inlineIndex, inline] of paragraph.inlines.entries()) {
+ assertNonEmpty(inline.id, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.id`);
+ if (ids.has(inline.id)) throw new Error(`${label} repeats inline id ${inline.id}.`);
+ ids.add(inline.id);
+ if (inline.kind === "text") {
+ if (inline.text.length === 0) throw new Error(`${label} contains an empty text run.`);
+ hasText ||= inline.text.trim().length > 0;
+ assertRunStyle(inline.style, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.style`);
+ const inlineTypography = inheritedTypography(paragraphTypography, inline.style);
+ assertTypography(inlineTypography, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.typography`);
+ if (inline.direction !== undefined && !["auto", "ltr", "rtl"].includes(inline.direction)) {
+ throw new Error(`${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.direction is invalid.`);
+ }
+ } else if (inline.kind !== "break") throw new Error(`${label} contains an unsupported inline.`);
+ }
+ }
+ if (!hasText) throw new Error(`${label} contains no visible text.`);
+}
+
+function assertBoxDecoration(decoration: VisualTextBoxDecoration, label: string): void {
+ if (decoration.fill !== undefined) assertColorPaint(decoration.fill, `${label}.fill`);
+ for (const [name, value] of Object.entries(decoration.paddingPx)) nonNegative(value, `${label}.paddingPx.${name}`);
+ for (const [name, value] of Object.entries(decoration.radiiPx)) nonNegative(value, `${label}.radiiPx.${name}`);
+ if (decoration.border !== undefined) {
+ assertColorPaint(decoration.border.paint, `${label}.border.paint`);
+ if (!["solid", "dashed", "dotted"].includes(decoration.border.style)) {
+ throw new Error(`${label}.border.style is invalid.`);
+ }
+ for (const [name, value] of Object.entries(decoration.border.widthsPx)) nonNegative(value, `${label}.border.widthsPx.${name}`);
+ }
+ for (const [index, shadow] of decoration.shadows.entries()) {
+ assertColorPaint(shadow.paint, `${label}.shadows.${index}.paint`);
+ finite(shadow.offsetX, `${label}.shadows.${index}.offsetX`);
+ finite(shadow.offsetY, `${label}.shadows.${index}.offsetY`);
+ nonNegative(shadow.blurPx, `${label}.shadows.${index}.blurPx`);
+ finite(shadow.spreadPx, `${label}.shadows.${index}.spreadPx`);
+ }
+ if (decoration.tail !== undefined) {
+ if (!["top", "right", "bottom", "left"].includes(decoration.tail.side)) {
+ throw new Error(`${label}.tail.side is invalid.`);
+ }
+ finite(decoration.tail.offset, `${label}.tail.offset`);
+ nonNegative(decoration.tail.widthPx, `${label}.tail.widthPx`);
+ nonNegative(decoration.tail.heightPx, `${label}.tail.heightPx`);
+ assertColorPaint(decoration.tail.paint, `${label}.tail.paint`);
+ }
+}
+
+function assertTextPaint(paint: VisualTextPaintLayer, label: string): void {
+ if (paint.kind === "fill") return assertColorPaint(paint.paint, `${label}.paint`);
+ if (paint.kind === "stroke") {
+ assertColorPaint(paint.paint, `${label}.paint`);
+ if (!["inside", "center", "outside"].includes(paint.placement)) {
+ throw new Error(`${label}.placement is invalid.`);
+ }
+ return nonNegative(paint.widthPx, `${label}.widthPx`);
+ }
+ if (paint.kind === "shadow") {
+ assertColorPaint(paint.paint, `${label}.paint`);
+ finite(paint.offsetX, `${label}.offsetX`);
+ finite(paint.offsetY, `${label}.offsetY`);
+ nonNegative(paint.blurPx, `${label}.blurPx`);
+ finite(paint.spreadPx, `${label}.spreadPx`);
+ return;
+ }
+ if (paint.kind === "glow") {
+ assertColorPaint(paint.paint, `${label}.paint`);
+ nonNegative(paint.blurPx, `${label}.blurPx`);
+ finite(paint.spreadPx, `${label}.spreadPx`);
+ return;
+ }
+ if (paint.kind !== "box") throw new Error(`${label} has an unsupported Paint kind.`);
+ if (paint.continuity === "joined" && !["line", "word", "grapheme"].includes(paint.target)) {
+ throw new Error(`${label} joined continuity is invalid for ${paint.target}.`);
+ }
+ assertBoxDecoration(paint.decoration, `${label}.decoration`);
+}
+
+function assertTextFlow(flow: VisualTextFlow, label: string): void {
+ if (!(["hug", "fixed"] as const).includes(flow.inlineSize)
+ || !(["hug", "fixed"] as const).includes(flow.blockSize)
+ || !(["start", "center", "end", "justify"] as const).includes(flow.inlineAlign)
+ || !(["start", "center", "end"] as const).includes(flow.blockAlign)
+ || !(["none", "word", "grapheme"] as const).includes(flow.wrap)
+ || !(["visible", "clip", "ellipsis", "shrink"] as const).includes(flow.overflow)
+ || !(["line-box", "cap-height", "ink"] as const).includes(flow.metricEdge)) {
+ throw new Error(`${label} contains an unsupported flow enum.`);
+ }
+ if (flow.form.kind === "point" && (flow.inlineSize !== "hug" || flow.blockSize !== "hug" || flow.wrap !== "none")) {
+ throw new Error(`${label} Point Text must hug both axes and cannot soft-wrap.`);
+ }
+ for (const [name, value] of Object.entries(flow.paddingPx)) nonNegative(value, `${label}.paddingPx.${name}`);
+ if (!Number.isSafeInteger(flow.columns) || flow.columns <= 0) throw new Error(`${label}.columns must be positive.`);
+ nonNegative(flow.columnGapPx, `${label}.columnGapPx`);
+ if (flow.maxLines !== undefined && (!Number.isSafeInteger(flow.maxLines) || flow.maxLines <= 0)) {
+ throw new Error(`${label}.maxLines must be positive.`);
+ }
+ if (flow.maxLines !== undefined && flow.overflow !== "ellipsis" && flow.overflow !== "shrink") {
+ throw new Error(`${label}.maxLines is valid only for ellipsis or shrink.`);
+ }
+ if (flow.overflow === "shrink") {
+ if (flow.minimumScale === undefined || !Number.isFinite(flow.minimumScale) || flow.minimumScale <= 0 || flow.minimumScale > 1) {
+ throw new Error(`${label}.minimumScale is required in (0, 1] for shrink.`);
+ }
+ } else if (flow.minimumScale !== undefined) throw new Error(`${label}.minimumScale is valid only for shrink.`);
+}
+
+function assertTextSequences(
+ sequences: readonly VisualTextSequenceAnimation[],
+ durationFrames: number,
+ label: string,
+): void {
+ const ids = new Set<string>();
+ for (const [index, sequence] of sequences.entries()) {
+ const item = `${label}.${index}`;
+ assertNonEmpty(sequence.id, `${item}.id`);
+ if (ids.has(sequence.id)) throw new Error(`${label} repeats ${sequence.id}.`);
+ ids.add(sequence.id);
+ if (!(["paragraph", "line", "run", "word", "grapheme"] as const).includes(sequence.unit)
+ || !(["forward", "reverse", "random"] as const).includes(sequence.order)) {
+ throw new Error(`${item} unit or order is invalid.`);
+ }
+ if (!Number.isSafeInteger(sequence.range.start) || !Number.isSafeInteger(sequence.range.endExclusive)
+ || sequence.range.start < 0 || sequence.range.endExclusive <= sequence.range.start
+ || !Number.isSafeInteger(sequence.startFrame) || sequence.startFrame < 0 || sequence.startFrame > durationFrames
+ || !Number.isSafeInteger(sequence.unitDurationFrames) || sequence.unitDurationFrames <= 0
+ || !Number.isSafeInteger(sequence.staggerFrames) || sequence.staggerFrames < 0
+ || !Number.isSafeInteger(sequence.cycles) || sequence.cycles <= 0
+ || (sequence.seed !== undefined && !Number.isSafeInteger(sequence.seed))) {
+ throw new Error(`${item} frame domain or range is invalid.`);
+ }
+ if ((sequence.order === "random") !== (sequence.seed !== undefined)) {
+ throw new Error(`${item} random order requires one explicit seed, and other orders forbid it.`);
+ }
+ const lastUnitEnd = sequence.startFrame
+ + (sequence.range.endExclusive - sequence.range.start - 1) * sequence.staggerFrames
+ + sequence.unitDurationFrames * sequence.cycles;
+ if (lastUnitEnd > durationFrames) throw new Error(`${item} animation exceeds its Present span.`);
+ if (sequence.keyframes.length < 2 || sequence.keyframes[0]?.atProgress !== 0 || sequence.keyframes.at(-1)?.atProgress !== 1) {
+ throw new Error(`${item} keyframes must cover progress [0, 1].`);
+ }
+ let previous = -1;
+ for (const [frameIndex, keyframe] of sequence.keyframes.entries()) {
+ if (!Number.isFinite(keyframe.atProgress) || keyframe.atProgress <= previous || keyframe.atProgress < 0 || keyframe.atProgress > 1) {
+ throw new Error(`${item}.keyframes.${frameIndex} progress is invalid.`);
+ }
+ assertStyle(keyframe.style, `${item}.keyframes.${frameIndex}.style`);
+ if (keyframe.style.some((declaration) => !ANIMATABLE_TEXT_UNIT_STYLES.has(declaration.name))) {
+ throw new Error(`${item}.keyframes.${frameIndex} animates an unsupported text-unit property.`);
+ }
+ previous = keyframe.atProgress;
+ }
+ }
+}
+
+function assertPathCommands(path: readonly VisualVectorPathCommand[], label: string): void {
+ if (path.length < 2 || path[0]?.kind !== "move") throw new Error(`${label} must begin with move and contain drawable geometry.`);
+ if (!path.some((command) => command.kind === "line" || command.kind === "quadratic" || command.kind === "cubic")) {
+ throw new Error(`${label} contains no drawable geometry.`);
+ }
+ for (const [index, command] of path.entries()) {
+ for (const [name, value] of Object.entries(command)) {
+ if (name !== "kind") finite(value as number, `${label}.${index}.${name}`);
+ }
+ }
+}
+
function assertAnimation(animation: VisualAnimation | undefined, durationFrames: number, label: string): void {
if (animation === undefined) return;
if (animation.keyframes.length < 2) throw new Error(`${label} animation must contain at least two keyframes.`);
@@ -397,19 +980,54 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
}
}
if (element.kind === "text" && element.fonts !== undefined) {
- if (element.fonts.length === 0) throw new Error(`${trackId}.${present.id}.${element.id} has an empty font stack.`);
- const faces = new Set<string>();
- for (const [index, font] of element.fonts.entries()) {
- assertFontArtifactRef(font, `${trackId}.${present.id}.${element.id}.fonts.${index}`);
- const face = digestOf(font);
- if (faces.has(face)) throw new Error(`${trackId}.${present.id}.${element.id} has a duplicate font face.`);
- faces.add(face);
- }
+ assertExactFonts(element.fonts, `${trackId}.${present.id}.${element.id}.fonts`);
const ownedFontStyles = new Set(["font", "font-family", "font-style", "font-synthesis", "font-weight"]);
if (element.style.some((declaration) => ownedFontStyles.has(declaration.name))) {
throw new Error(`${trackId}.${present.id}.${element.id} exact fonts conflict with a raw font style.`);
}
}
+ if (element.kind === "text-flow" || element.kind === "path-text") {
+ const label = `${trackId}.${present.id}.${element.id}`;
+ assertTextDocument(element.document, element.typography, `${label}.document`);
+ assertTypography(element.typography, `${label}.typography`);
+ const boxKeys = new Set<string>();
+ for (const [index, paint] of element.paints.entries()) {
+ assertTextPaint(paint, `${label}.paints.${index}`);
+ if (paint.kind === "box") {
+ const key = `${paint.target}:${paint.continuity}`;
+ if (boxKeys.has(key)) throw new Error(`${label} repeats Box Paint ${key}.`);
+ boxKeys.add(key);
+ }
+ }
+ assertTextSequences(element.sequences, present.span.endFrameExclusive - present.span.startFrame, `${label}.sequences`);
+ if (element.kind === "text-flow") assertTextFlow(element.flow, `${label}.flow`);
+ else {
+ assertPathCommands(element.path, `${label}.path`);
+ if (!(["left", "right"] as const).includes(element.side)
+ || !(["follow", "upright"] as const).includes(element.orientation)
+ || !(["start", "center", "end"] as const).includes(element.align)
+ || !(["visible", "clip"] as const).includes(element.overflow)) {
+ throw new Error(`${label} contains an unsupported Path Text enum.`);
+ }
+ nonNegative(element.startMarginPx, `${label}.startMarginPx`);
+ nonNegative(element.endMarginPx, `${label}.endMarginPx`);
+ if (element.marginAnimation !== undefined) {
+ const frames = element.marginAnimation.keyframes;
+ if (frames.length < 2 || frames[0]?.atFrame !== 0
+ || frames.at(-1)?.atFrame !== present.span.endFrameExclusive - present.span.startFrame) {
+ throw new Error(`${label}.marginAnimation must cover the complete Present span.`);
+ }
+ let previous = -1;
+ for (const [index, keyframe] of frames.entries()) {
+ if (!Number.isSafeInteger(keyframe.atFrame) || keyframe.atFrame <= previous) {
+ throw new Error(`${label}.marginAnimation.${index} has an invalid frame.`);
+ }
+ nonNegative(keyframe.startMarginPx, `${label}.marginAnimation.${index}.startMarginPx`);
+ previous = keyframe.atFrame;
+ }
+ }
+ }
+ }
if (element.kind === "surface") {
assertCompositableSurfaceRef(element.surface, `${trackId}.${present.id}.${element.id}.surface`);
if (element.surface.timing.kind === "still" && element.sampling !== undefined) {
@@ -439,14 +1057,20 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
)) throw new Error(`${trackId}.${present.id}.${element.id} Surface must exactly match its Present frame domain.`);
}
}
+ if (element.kind === "mask") {
+ if (!["alpha", "luminance"].includes(element.mode)
+ || element.maskElement === element.contentElement) {
+ throw new Error(`${trackId}.${present.id}.${element.id} has an invalid local mask.`);
+ }
+ }
}
if (roots.length !== 1) throw new Error(`${trackId}.${present.id} must contain exactly one root element.`);
for (const element of present.elements) {
if (element.parent !== undefined && !elements.has(element.parent)) {
throw new Error(`${trackId}.${present.id}.${element.id} references a foreign parent.`);
}
- if (element.parent !== undefined && elements.get(element.parent)?.kind !== "box") {
- throw new Error(`${trackId}.${present.id}.${element.id} must have a box parent.`);
+ if (element.parent !== undefined && !["box", "mask"].includes(elements.get(element.parent)?.kind ?? "")) {
+ throw new Error(`${trackId}.${present.id}.${element.id} must have a box or mask parent.`);
}
const visited = new Set<string>();
let cursor: VisualElement | undefined = element;
@@ -456,6 +1080,21 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
cursor = elements.get(cursor.parent);
}
}
+ for (const element of present.elements) {
+ if (element.kind !== "mask") continue;
+ const direct = present.elements.filter((candidate) => candidate.parent === element.id);
+ if (direct.length !== 2
+ || !direct.some((candidate) => candidate.id === element.maskElement)
+ || !direct.some((candidate) => candidate.id === element.contentElement)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} must own exactly its declared mask and content roots.`);
+ }
+ const maskRoot = direct.find((candidate) => candidate.id === element.maskElement)!;
+ if (!["text", "text-flow", "path-text", "image", "surface"].includes(maskRoot.kind)
+ || (maskRoot.kind === "surface" && maskRoot.surface.timing.kind !== "still")
+ || present.elements.some((candidate) => candidate.parent === maskRoot.id)) {
+ throw new Error(`${trackId}.${present.id}.${element.id} mask source must be one terminal owned text, image or still Surface.`);
+ }
+ }
}
function normalizeStyle(style: readonly VisualStyleDeclaration[]): VisualStyleDeclaration[] {
@@ -492,6 +1131,13 @@ function normalizeElement(element: VisualElement): VisualElement {
...(element.animation === undefined ? {} : { animation: normalizeAnimation(element.animation) }),
};
if (element.kind === "box") return { ...common, kind: "box" };
+ if (element.kind === "mask") return {
+ ...common,
+ kind: "mask",
+ mode: element.mode,
+ maskElement: element.maskElement,
+ contentElement: element.contentElement,
+ };
if (element.kind === "text") {
return {
...common,
@@ -510,6 +1156,22 @@ function normalizeElement(element: VisualElement): VisualElement {
}),
};
}
+ if (element.kind === "text-flow" || element.kind === "path-text") {
+ const copy = structuredClone(element);
+ return {
+ ...copy,
+ ...common,
+ kind: element.kind,
+ sequences: element.sequences.map((sequence) => ({
+ ...sequence,
+ range: { ...sequence.range },
+ keyframes: sequence.keyframes.map((keyframe) => ({
+ ...keyframe,
+ style: normalizeStyle(keyframe.style),
+ })),
+ })),
+ } as VisualTextFlowElement | VisualPathTextElement;
+ }
if (element.kind === "surface") {
return {
...common,
diff --git a/packages/composition/test/render.test.ts b/packages/composition/test/render.test.ts
index 52e30368..dcf592f7 100644
--- a/packages/composition/test/render.test.ts
+++ b/packages/composition/test/render.test.ts
@@ -155,3 +155,67 @@ test("animated materialized Surfaces must exactly share the Present frame domain
tracks: [invalid],
}), space), /must exactly match its Present frame domain/u);
});
+
+test("a local mask owns exactly one mask root and one content root inside its Present", () => {
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ visualIr: "svml.visual-ir@1",
+ id: "masked-text",
+ presents: [{
+ id: "mask",
+ span: { startFrame: 0, endFrameExclusive: 60 },
+ stacking: { order: 4, tieBreak: "mask" },
+ elements: [
+ {
+ id: "local-mask", kind: "mask", order: 0, mode: "alpha",
+ maskElement: "letters", contentElement: "material",
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ },
+ {
+ id: "letters", parent: "local-mask", kind: "text", order: 1, text: "MASK", fonts: [font],
+ style: [{ name: "font-size", value: "180px" }, { name: "color", value: "#ffffff" }],
+ },
+ {
+ id: "material", parent: "local-mask", kind: "box", order: 2,
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }, { name: "background", value: "linear-gradient(90deg,#ff0000,#0000ff)" }],
+ },
+ ],
+ }],
+ });
+ assert.doesNotThrow(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1",
+ id: "mask-composition",
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [track],
+ }), space));
+
+ const invalid = structuredClone(track) as VisualTrack;
+ const root = invalid.presents[0]!.elements[0]!;
+ assert(root.kind === "mask");
+ const broken = sealVisualTrack({
+ ...invalid,
+ presents: [{
+ ...invalid.presents[0]!,
+ elements: [{ ...root, contentElement: "foreign" }, ...invalid.presents[0]!.elements.slice(1)],
+ }],
+ });
+ assert.throws(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1", id: "broken-mask",
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [broken],
+ }), space), /declared mask and content roots/u);
+
+ const nested = sealVisualTrack({
+ ...track,
+ presents: [{
+ ...track.presents[0]!,
+ elements: [
+ ...track.presents[0]!.elements,
+ { id: "hidden-child", parent: "letters", kind: "box", order: 3, style: [] },
+ ],
+ }],
+ });
+ assert.throws(() => assertCompositionIdentity(sealComposition({
+ contract: "svml.composition@1", id: "nested-mask-source",
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [nested],
+ }), space), /must have a box or mask parent/u);
+});
diff --git a/packages/deck-track/README.md b/packages/deck-track/README.md
new file mode 100644
index 00000000..b5648f5e
--- /dev/null
+++ b/packages/deck-track/README.md
@@ -0,0 +1,34 @@
+# `@narratage/deck-track`
+
+The official, deliberately narrow depth-stack Deck author package.
+
+`DepthStack` owns ordered Cards, semantic activation points, a finite visible neighborhood,
+relative-depth poses and one deterministic whole-collection reflow. Card pixels reuse the focused
+Media layer lowerer, but Deck is not a Media mode and exports only an ordinary peer `VisualTrack`.
+
+```xml
+<deck:DepthStack
+ id="proof-stack"
+ map={timing.map}
+ space={speech.space}
+ canvas={vertical}
+ frame={layout.proof-stack}
+ until={story.selection.proof}
+ appearance={studio.deck.proof}
+>
+ <deck:Card id="proof-1" source={proof1.image} extent={proof1.extent} at={story.moment.proof1}/>
+ <deck:Card id="proof-2" source={proof2.video} at={story.moment.proof2}/>
+</deck:DepthStack>
+```
+
+The parent Recipe owns visibility, relative-depth pose progression, frame Paint, whole-group
+motion and reflow. A Card Recipe may additionally select explicit future/past playback. Timed
+`continue` is legal only with an active `loop-start` clock, so preview and trail sampling can never
+silently depend on renderer playback history.
+
+Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs and
+media metadata are never treated as label truth.
+
+The package has no Provider, Need, queue, credential, global z band or cross-Track input. Another
+Deck family can install independently and lower to the same terminal `VisualTrack` without changing
+this package, Core, Film, Composition or HyperFrames.
diff --git a/packages/deck-track/package.json b/packages/deck-track/package.json
new file mode 100644
index 00000000..85954151
--- /dev/null
+++ b/packages/deck-track/package.json
@@ -0,0 +1,27 @@
+{
+ "name": "@narratage/deck-track",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "svml": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@narratage/component-kit": "workspace:*",
+ "@narratage/composition": "workspace:*",
+ "@narratage/elaborator": "workspace:*",
+ "@narratage/media": "workspace:*",
+ "@narratage/media-track": "workspace:*",
+ "@narratage/narrative": "workspace:*",
+ "@narratage/program-space": "workspace:*",
+ "@narratage/protocol": "workspace:*",
+ "@narratage/semantic-map": "workspace:*",
+ "@narratage/spatial": "workspace:*",
+ "@narratage/svs": "workspace:*",
+ "@narratage/temporal": "workspace:*",
+ "@narratage/text": "workspace:*"
+ }
+}
diff --git a/packages/deck-track/src/activation.ts b/packages/deck-track/src/activation.ts
new file mode 100644
index 00000000..28e9eb20
--- /dev/null
+++ b/packages/deck-track/src/activation.ts
@@ -0,0 +1,38 @@
+import { createTextSurfaceHostFacet } from "@narratage/text";
+
+import {
+ decodeDepthStackLabelSurface,
+ decodeDepthStackSurface,
+ depthStackComponent,
+ depthStackManifest,
+ depthStackModuleRef,
+ depthStackSurfaceImplementationDigests,
+} from "./index.js";
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/deck-track",
+ modules: [{
+ manifest: depthStackManifest,
+ specifiers: [depthStackModuleRef.name, `${depthStackModuleRef.name}@1`],
+ }],
+ components: [depthStackComponent],
+ hostFacets: [
+ createTextSurfaceHostFacet({
+ module: depthStackModuleRef,
+ surface: "label",
+ mode: "structured",
+ implementationDigest: depthStackSurfaceImplementationDigests.label,
+ handler: decodeDepthStackLabelSurface,
+ }),
+ createTextSurfaceHostFacet({
+ module: depthStackModuleRef,
+ surface: "track",
+ mode: "structured",
+ implementationDigest: depthStackSurfaceImplementationDigests.track,
+ handler: decodeDepthStackSurface,
+ }),
+ ],
+};
+
+export default svmlPackage;
diff --git a/packages/deck-track/src/author.ts b/packages/deck-track/src/author.ts
new file mode 100644
index 00000000..a6961a52
--- /dev/null
+++ b/packages/deck-track/src/author.ts
@@ -0,0 +1,217 @@
+import {
+ decodeMediaFit,
+ decodeMediaFramePaint,
+ decodeMediaMotion,
+ decodeMediaPresentation,
+ decodeMediaSampleSpec,
+ mediaAppearanceKeys,
+} from "@narratage/media-track";
+import type {
+ MediaPaintLayerSpec,
+ MediaSampleLayerSpec,
+} from "@narratage/media-track";
+import type { ContentFit } from "@narratage/spatial";
+import type { SvsRecipe } from "@narratage/svs";
+
+import {
+ sealDepthStackCardSpec,
+ sealDepthStackSpec,
+} from "./program.js";
+import type {
+ DeckCardTone,
+ DepthStackCardSpec,
+ DepthStackPoseStep,
+ DepthStackSpec,
+} from "./types.js";
+
+const DECK_KEYS = [
+ "visible-previous", "visible-next", "wrap",
+ "current-x", "current-y", "current-scale", "current-rotation", "current-opacity", "current-stacking",
+ "current-brightness", "current-contrast", "current-saturation",
+ "previous-x-step", "previous-y-step", "previous-scale-step", "previous-rotation-step",
+ "previous-rotation-mode", "previous-opacity-step", "previous-stacking-step",
+ "previous-brightness-step", "previous-contrast-step", "previous-saturation-step",
+ "next-x-step", "next-y-step", "next-scale-step", "next-rotation-step",
+ "next-rotation-mode", "next-opacity-step", "next-stacking-step",
+ "next-brightness-step", "next-contrast-step", "next-saturation-step",
+ "reflow-frames", "reflow-easing", "playback-future", "playback-past",
+] as const;
+
+function fail(recipe: SvsRecipe, message: string): never {
+ throw new Error(`DepthStack Recipe ${recipe.path} ${message}`);
+}
+
+function optionalNumber(recipe: SvsRecipe, name: string): number | undefined {
+ const value = recipe.properties[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
+ return value;
+}
+
+function number(recipe: SvsRecipe, name: string, fallback: number): number {
+ return optionalNumber(recipe, name) ?? fallback;
+}
+
+function integer(recipe: SvsRecipe, name: string, fallback: number): number {
+ const value = number(recipe, name, fallback);
+ if (!Number.isSafeInteger(value)) fail(recipe, `${name} must be an integer.`);
+ return value;
+}
+
+function optionalString(recipe: SvsRecipe, name: string): string | undefined {
+ const value = recipe.properties[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
+ return value.trim();
+}
+
+function oneOf<T extends string>(
+ recipe: SvsRecipe,
+ name: string,
+ values: readonly T[],
+ fallback: T,
+): T {
+ const value = optionalString(recipe, name) ?? fallback;
+ if (!values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
+ return value as T;
+}
+
+function boolean(recipe: SvsRecipe, name: string, fallback: boolean): boolean {
+ const value = recipe.properties[name];
+ if (value === undefined) return fallback;
+ if (typeof value !== "boolean") fail(recipe, `${name} must be boolean.`);
+ return value;
+}
+
+function mediaRecipe(recipe: SvsRecipe, keys: readonly string[]): SvsRecipe {
+ const selected: Record<string, SvsRecipe["properties"][string]> = {};
+ for (const key of keys) {
+ const value = recipe.properties[key];
+ if (value !== undefined) selected[key] = value;
+ }
+ return { ...recipe, properties: selected };
+}
+
+function tone(recipe: SvsRecipe, prefix: string, fallback: DeckCardTone): DeckCardTone {
+ return {
+ brightness: number(recipe, `${prefix}-brightness`, fallback.brightness),
+ contrast: number(recipe, `${prefix}-contrast`, fallback.contrast),
+ saturation: number(recipe, `${prefix}-saturation`, fallback.saturation),
+ };
+}
+
+function step(
+ recipe: SvsRecipe,
+ prefix: "previous" | "next",
+ defaults: DepthStackPoseStep,
+): DepthStackPoseStep {
+ return {
+ xPerDepthPx: number(recipe, `${prefix}-x-step`, defaults.xPerDepthPx),
+ yPerDepthPx: number(recipe, `${prefix}-y-step`, defaults.yPerDepthPx),
+ scalePerDepth: number(recipe, `${prefix}-scale-step`, defaults.scalePerDepth),
+ rotationPerDepthDeg: number(recipe, `${prefix}-rotation-step`, defaults.rotationPerDepthDeg),
+ rotationMode: oneOf(recipe, `${prefix}-rotation-mode`, ["linear", "alternate"] as const, defaults.rotationMode),
+ opacityPerDepth: number(recipe, `${prefix}-opacity-step`, defaults.opacityPerDepth),
+ stackingPerDepth: integer(recipe, `${prefix}-stacking-step`, defaults.stackingPerDepth),
+ tonePerDepth: tone(recipe, `${prefix}`, defaults.tonePerDepth),
+ };
+}
+
+function assertKnownKeys(recipe: SvsRecipe): void {
+ const allowed = new Set<string>([
+ ...DECK_KEYS,
+ ...mediaAppearanceKeys.fit,
+ ...mediaAppearanceKeys.sample,
+ ...mediaAppearanceKeys.frame,
+ ...mediaAppearanceKeys.motion,
+ ]);
+ const unknown = Object.keys(recipe.properties).filter((key) => !allowed.has(key));
+ if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+}
+
+export function decodeDepthStackSpec(recipe: SvsRecipe): DepthStackSpec {
+ assertKnownKeys(recipe);
+ const motionRecipe = mediaRecipe(recipe, mediaAppearanceKeys.motion);
+ const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+ const previousDefaults: DepthStackPoseStep = {
+ xPerDepthPx: 0,
+ yPerDepthPx: 28,
+ scalePerDepth: 0.94,
+ rotationPerDepthDeg: -2.5,
+ rotationMode: "alternate",
+ opacityPerDepth: 0.82,
+ stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.92, contrast: 1, saturation: 0.86 },
+ };
+ const nextDefaults: DepthStackPoseStep = {
+ xPerDepthPx: 0,
+ yPerDepthPx: -20,
+ scalePerDepth: 0.92,
+ rotationPerDepthDeg: 2,
+ rotationMode: "alternate",
+ opacityPerDepth: 0.72,
+ stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.88, contrast: 1, saturation: 0.78 },
+ };
+ return sealDepthStackSpec({
+ contract: "svml.depth-stack-spec@1",
+ visibility: {
+ previous: integer(recipe, "visible-previous", 2),
+ next: integer(recipe, "visible-next", 1),
+ wrap: boolean(recipe, "wrap", false),
+ },
+ poses: {
+ current: {
+ xPx: number(recipe, "current-x", 0),
+ yPx: number(recipe, "current-y", 0),
+ scale: number(recipe, "current-scale", 1),
+ rotationDeg: number(recipe, "current-rotation", 0),
+ opacity: number(recipe, "current-opacity", 1),
+ stacking: integer(recipe, "current-stacking", 0),
+ tone: tone(recipe, "current", { brightness: 1, contrast: 1, saturation: 1 }),
+ },
+ previous: step(recipe, "previous", previousDefaults),
+ next: step(recipe, "next", nextDefaults),
+ },
+ reflow: {
+ durationFrames: integer(recipe, "reflow-frames", 8),
+ easing: oneOf(recipe, "reflow-easing", ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
+ },
+ presentation: decodeMediaPresentation(frameRecipe),
+ motion: decodeMediaMotion(motionRecipe),
+ stackingOrder: integer(recipe, "stack-order", 30),
+ });
+}
+
+export function decodeDepthStackCardSpec(recipe: SvsRecipe, id: string): DepthStackCardSpec {
+ assertKnownKeys(recipe);
+ return sealDepthStackCardSpec({
+ contract: "svml.depth-stack-card-spec@1",
+ id,
+ playback: {
+ future: oneOf(recipe, "playback-future", ["hold-head", "continue"] as const, "hold-head"),
+ past: oneOf(recipe, "playback-past", ["hold-tail", "continue", "hide"] as const, "hold-tail"),
+ },
+ });
+}
+
+export function decodeDepthStackMaterial(
+ recipe: SvsRecipe,
+ id: string,
+ sourceKind: "still" | "timed" | "surface",
+): {
+ readonly fit: ContentFit;
+ readonly framePaint?: MediaPaintLayerSpec;
+ readonly sample: MediaSampleLayerSpec;
+} {
+ assertKnownKeys(recipe);
+ const fitRecipe = mediaRecipe(recipe, mediaAppearanceKeys.fit);
+ const sampleRecipe = mediaRecipe(recipe, [...mediaAppearanceKeys.fit, ...mediaAppearanceKeys.sample]);
+ const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+ const framePaint = decodeMediaFramePaint(frameRecipe, `${id}:frame-paint`);
+ return {
+ fit: decodeMediaFit(fitRecipe),
+ ...(framePaint === undefined ? {} : { framePaint }),
+ sample: decodeMediaSampleSpec(sampleRecipe, `${id}:sample`, sourceKind),
+ };
+}
diff --git a/packages/deck-track/src/component.ts b/packages/deck-track/src/component.ts
new file mode 100644
index 00000000..8c7cdb6c
--- /dev/null
+++ b/packages/deck-track/src/component.ts
@@ -0,0 +1,121 @@
+import type { ComponentPackage, ProducerHandlerContext } from "@narratage/component-kit";
+import type { ProgramSpace } from "@narratage/program-space";
+import { canonicalize } from "@narratage/protocol";
+import type { StoredValue } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import type { CanvasSpace, SpatialFrame } from "@narratage/spatial";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import type { MediaLayerSet } from "@narratage/media-track";
+
+import { renderDepthStack } from "./lower.js";
+import { depthStackProducers, depthStackTypes } from "./manifest.js";
+import {
+ appendDepthStackMomentCard,
+ assertDepthStackProgram,
+ createDepthStackCardSet,
+ depthStackImplementationDigests,
+ depthStackValidatorDigests,
+ finalizeDepthStackAtProgramEnd,
+ finalizeDepthStackUntilMoment,
+ finalizeDepthStackUntilSelection,
+} from "./program.js";
+import type {
+ DepthStackCardLabel,
+ DepthStackCardSet,
+ DepthStackCardSpec,
+ DepthStackHeader,
+ DepthStackProgram,
+ DepthStackSpec,
+} from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+ if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+ return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+function finalizeInputs(inputs: ProducerHandlerContext["inputs"]) {
+ return {
+ set: inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),
+ header: inline<DepthStackHeader>(inputs.header?.value, "DepthStackHeader"),
+ frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ spec: inline<DepthStackSpec>(inputs.spec?.value, "DepthStackSpec"),
+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ };
+}
+
+export const depthStackComponent = {
+ name: "@narratage/deck-track",
+ producers: [
+ {
+ producer: depthStackProducers.createCards,
+ implementationDigest: depthStackImplementationDigests.createCards,
+ handler: () => ({ outputs: { set: output(createDepthStackCardSet()) }, needs: {} }),
+ },
+ {
+ producer: depthStackProducers.appendMomentCard,
+ implementationDigest: depthStackImplementationDigests.appendMomentCard,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendDepthStackMomentCard(
+ inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),
+ inline<MediaLayerSet>(inputs.material?.value, "MediaLayerSet"),
+ inline<DepthStackCardLabel>(inputs.label?.value, "DepthStackCardLabel"),
+ inline<DepthStackCardSpec>(inputs.spec?.value, "DepthStackCardSpec"),
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMomentRef"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: depthStackProducers.finalizeProgramEnd,
+ implementationDigest: depthStackImplementationDigests.finalizeProgramEnd,
+ handler: ({ inputs }) => {
+ const value = finalizeInputs(inputs);
+ return { outputs: { program: output(finalizeDepthStackAtProgramEnd(
+ value.set, value.header, value.frame, value.spec, value.space,
+ )) }, needs: {} };
+ },
+ },
+ {
+ producer: depthStackProducers.finalizeUntilMoment,
+ implementationDigest: depthStackImplementationDigests.finalizeUntilMoment,
+ handler: ({ inputs }) => {
+ const value = finalizeInputs(inputs);
+ return { outputs: { program: output(finalizeDepthStackUntilMoment(
+ value.set, value.header, value.frame, value.spec,
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<NarrativeMomentRef>(inputs.terminal?.value, "NarrativeMomentRef"), value.space,
+ )) }, needs: {} };
+ },
+ },
+ ...([depthStackProducers.finalizeUntilSelectionStart, depthStackProducers.finalizeUntilSelectionEnd] as const)
+ .map((producer, index) => ({
+ producer,
+ implementationDigest: index === 0
+ ? depthStackImplementationDigests.finalizeUntilSelectionStart
+ : depthStackImplementationDigests.finalizeUntilSelectionEnd,
+ handler: ({ inputs }: ProducerHandlerContext) => {
+ const value = finalizeInputs(inputs);
+ return { outputs: { program: output(finalizeDepthStackUntilSelection(
+ value.set, value.header, value.frame, value.spec,
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<NarrativeSelectionRef>(inputs.terminal?.value, "NarrativeSelectionRef"),
+ index === 0 ? "start" : "end", value.space,
+ )) }, needs: {} };
+ },
+ })),
+ {
+ producer: depthStackProducers.render,
+ implementationDigest: depthStackImplementationDigests.render,
+ handler: ({ inputs }) => ({ outputs: { track: output(renderDepthStack(
+ inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<DepthStackProgram>(inputs.program?.value, "DepthStackProgram"),
+ )) }, needs: {} }),
+ },
+ ],
+ validators: [{
+ type: depthStackTypes.program,
+ implementationDigest: depthStackValidatorDigests.program,
+ handler: ({ value }) => assertDepthStackProgram(inline<DepthStackProgram>(value, "DepthStackProgram")),
+ }],
+} satisfies ComponentPackage;
diff --git a/packages/deck-track/src/fragment.ts b/packages/deck-track/src/fragment.ts
new file mode 100644
index 00000000..1e0c7dad
--- /dev/null
+++ b/packages/deck-track/src/fragment.ts
@@ -0,0 +1,169 @@
+import { artifactTypes } from "@narratage/artifact";
+import { compositionTypes } from "@narratage/composition";
+import { sealGraphFragment } from "@narratage/elaborator";
+import type { FragmentOperation, GraphFragment } from "@narratage/elaborator";
+import { mediaTypes } from "@narratage/media";
+import { mediaTrackProducers, mediaTrackTypes } from "@narratage/media-track";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes } from "@narratage/program-space";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { spatialTypes } from "@narratage/spatial";
+
+import { depthStackProducers, depthStackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export type DepthStackFragmentCard = {
+ readonly suffix: string;
+ readonly sourceKind: "still" | "timed" | "surface";
+ readonly sourceName: string;
+ readonly extentName?: string;
+ readonly fitName: string;
+ readonly sampleSpecName: string;
+ readonly framePaintSpecName?: string;
+ readonly labelName: string;
+ readonly cardSpecName: string;
+ readonly momentName: string;
+};
+
+export type DepthStackFragmentTerminal =
+ | { readonly kind: "program-end" }
+ | { readonly kind: "moment" | "selection-start" | "selection-end"; readonly inputName: string };
+
+function sourceInput(card: DepthStackFragmentCard): GraphFragment["inputs"][number] {
+ const type = card.sourceKind === "still"
+ ? artifactTypes.blob
+ : card.sourceKind === "timed" ? mediaTypes.synchronized : mediaTypes.compositableSurface;
+ return { name: card.sourceName, type };
+}
+
+export function createDepthStackFragment(
+ cards: readonly DepthStackFragmentCard[],
+ terminal: DepthStackFragmentTerminal,
+ name = "@narratage/deck-track/dynamic-depth-stack@1",
+) {
+ if (cards.length === 0) throw new Error("DepthStack Fragment requires Cards.");
+ const inputs: Array<GraphFragment["inputs"][number]> = [
+ { name: "canvas", type: spatialTypes.canvas },
+ { name: "frame", type: spatialTypes.frame },
+ { name: "header", type: depthStackTypes.header },
+ { name: "map", type: semanticMapTypes.complete },
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "spec", type: depthStackTypes.spec },
+ ];
+ const operations: FragmentOperation[] = [{
+ id: "cards",
+ producer: depthStackProducers.createCards,
+ inputs: {},
+ result: { kind: "output", name: "set" },
+ }];
+ let cardSet = operation("cards");
+ for (const card of cards) {
+ inputs.push(sourceInput(card));
+ if (card.extentName !== undefined) inputs.push({ name: card.extentName, type: spatialTypes.extent });
+ inputs.push(
+ { name: card.fitName, type: spatialTypes.fit },
+ { name: card.sampleSpecName, type: mediaTrackTypes.sampleLayerSpec },
+ { name: card.labelName, type: depthStackTypes.cardLabel },
+ { name: card.cardSpecName, type: depthStackTypes.cardSpec },
+ { name: card.momentName, type: narrativeTypes.moment },
+ );
+ if (card.framePaintSpecName !== undefined) {
+ inputs.push({ name: card.framePaintSpecName, type: mediaTrackTypes.paintLayerSpec });
+ }
+ const layersId = `layers-${card.suffix}`;
+ operations.push({
+ id: layersId,
+ producer: mediaTrackProducers.createLayers,
+ inputs: {},
+ result: { kind: "output", name: "layers" },
+ });
+ let layers = operation(layersId);
+ if (card.framePaintSpecName !== undefined) {
+ const paintId = `paint-${card.suffix}`;
+ operations.push({
+ id: paintId,
+ producer: mediaTrackProducers.appendPaintLayer,
+ inputs: { layers, spec: input(card.framePaintSpecName) },
+ result: { kind: "output", name: "layers" },
+ });
+ layers = operation(paintId);
+ }
+ const sampleId = `sample-${card.suffix}`;
+ const producer = card.sourceKind === "still"
+ ? mediaTrackProducers.appendStillLayer
+ : card.sourceKind === "timed" ? mediaTrackProducers.appendTimedLayer : mediaTrackProducers.appendSurfaceLayer;
+ operations.push({
+ id: sampleId,
+ producer,
+ inputs: {
+ layers,
+ source: input(card.sourceName),
+ ...(card.extentName === undefined ? {} : { extent: input(card.extentName) }),
+ fit: input(card.fitName),
+ spec: input(card.sampleSpecName),
+ },
+ result: { kind: "output", name: "layers" },
+ });
+ const appendId = `append-${card.suffix}`;
+ operations.push({
+ id: appendId,
+ producer: depthStackProducers.appendMomentCard,
+ inputs: {
+ set: cardSet,
+ material: operation(sampleId),
+ label: input(card.labelName),
+ spec: input(card.cardSpecName),
+ map: input("map"),
+ moment: input(card.momentName),
+ space: input("space"),
+ },
+ result: { kind: "output", name: "set" },
+ });
+ cardSet = operation(appendId);
+ }
+ const terminalProducer = terminal.kind === "program-end"
+ ? depthStackProducers.finalizeProgramEnd
+ : terminal.kind === "moment" ? depthStackProducers.finalizeUntilMoment
+ : terminal.kind === "selection-start" ? depthStackProducers.finalizeUntilSelectionStart
+ : depthStackProducers.finalizeUntilSelectionEnd;
+ if (terminal.kind !== "program-end") {
+ inputs.push({
+ name: terminal.inputName,
+ type: terminal.kind === "moment" ? narrativeTypes.moment : narrativeTypes.selection,
+ });
+ }
+ operations.push({
+ id: "program",
+ producer: terminalProducer,
+ inputs: {
+ set: cardSet,
+ header: input("header"),
+ frame: input("frame"),
+ spec: input("spec"),
+ space: input("space"),
+ ...(terminal.kind === "program-end" ? {} : {
+ map: input("map"),
+ terminal: input(terminal.inputName),
+ }),
+ },
+ result: { kind: "output", name: "program" },
+ });
+ operations.push({
+ id: "track",
+ producer: depthStackProducers.render,
+ inputs: { canvas: input("canvas"), space: input("space"), program: operation("program") },
+ result: { kind: "output", name: "track" },
+ });
+ const semanticInputs = inputs.map(({ name: inputName }) => inputName);
+ return sealGraphFragment({
+ name,
+ inputs,
+ operations,
+ exports: [
+ { name: "program", type: depthStackTypes.program, root: operation("program"), semanticInputs, fidelity: "exact" },
+ { name: "track", type: compositionTypes.visualTrack, root: operation("track"), semanticInputs, fidelity: "exact" },
+ ],
+ });
+}
diff --git a/packages/deck-track/src/index.ts b/packages/deck-track/src/index.ts
new file mode 100644
index 00000000..6fcf6c51
--- /dev/null
+++ b/packages/deck-track/src/index.ts
@@ -0,0 +1,54 @@
+export {
+ decodeDepthStackCardSpec,
+ decodeDepthStackMaterial,
+ decodeDepthStackSpec,
+} from "./author.js";
+export { depthStackComponent } from "./component.js";
+export { createDepthStackFragment } from "./fragment.js";
+export type { DepthStackFragmentCard, DepthStackFragmentTerminal } from "./fragment.js";
+export {
+ decodeDepthStackLabelSurface,
+ decodeDepthStackSurface,
+} from "./surface.js";
+export { renderDepthStack } from "./lower.js";
+export {
+ depthStackCardLabelSchema,
+ depthStackCardSetSchema,
+ depthStackCardSpecSchema,
+ depthStackDependency,
+ depthStackHeaderSchema,
+ depthStackManifest,
+ depthStackManifestDigest,
+ depthStackModuleRef,
+ depthStackProducers,
+ depthStackProgramSchema,
+ depthStackSpecSchema,
+ depthStackSurfaceImplementationDigests,
+ depthStackTypes,
+} from "./manifest.js";
+export {
+ appendDepthStackCard,
+ appendDepthStackMomentCard,
+ assertDepthStackCardLabel,
+ assertDepthStackCardSet,
+ assertDepthStackCardSpec,
+ assertDepthStackHeader,
+ assertDepthStackProgram,
+ assertDepthStackProgramIdentity,
+ assertDepthStackSpec,
+ createDepthStackCardSet,
+ depthStackImplementationDigests,
+ depthStackValidatorDigests,
+ finalizeDepthStack,
+ finalizeDepthStackAtProgramEnd,
+ finalizeDepthStackUntilMoment,
+ finalizeDepthStackUntilSelection,
+ noDepthStackCardLabel,
+ resolveDepthStackPose,
+ resolveDepthStackState,
+ sealDepthStackCardLabel,
+ sealDepthStackCardSpec,
+ sealDepthStackHeader,
+ sealDepthStackSpec,
+} from "./program.js";
+export type * from "./types.js";
diff --git a/packages/deck-track/src/lower.ts b/packages/deck-track/src/lower.ts
new file mode 100644
index 00000000..cd12666f
--- /dev/null
+++ b/packages/deck-track/src/lower.ts
@@ -0,0 +1,369 @@
+import {
+ assertVisualTrackIdentity,
+ sealVisualTrack,
+} from "@narratage/composition";
+import type {
+ VisualAnimation,
+ VisualElement,
+ VisualStyleDeclaration,
+ VisualTimedSampling,
+ VisualTrack,
+} from "@narratage/composition";
+import {
+ lifecycleAnimationWindow,
+ lowerMediaItemElements,
+ resolveVisualSampling,
+ sustainAnimationWindow,
+} from "@narratage/media-track";
+import type {
+ MediaItemProgram,
+ MediaSampleLayerProgram,
+ MediaVisualTrim,
+} from "@narratage/media-track";
+import type { ProgramSpace } from "@narratage/program-space";
+import type { CanvasSpace, SpatialFrame } from "@narratage/spatial";
+
+import {
+ assertDepthStackProgramIdentity,
+ resolveDepthStackPose,
+ resolveDepthStackState,
+} from "./program.js";
+import type {
+ DepthStackCard,
+ DepthStackPose,
+ DepthStackProgram,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function px(value: number): string {
+ return `${value}px`;
+}
+
+function poseStyle(value: DepthStackPose): VisualStyleDeclaration[] {
+ return [
+ {
+ name: "filter",
+ value: `brightness(${value.tone.brightness}) contrast(${value.tone.contrast}) saturate(${value.tone.saturation})`,
+ },
+ { name: "opacity", value: value.opacity },
+ {
+ name: "transform",
+ value: `translate(${value.xPx}px,${value.yPx}px) rotate(${value.rotationDeg}deg) scale(${value.scale})`,
+ },
+ ];
+}
+
+function hiddenPose(program: DepthStackProgram, direction: "previous" | "next"): DepthStackPose {
+ const depth = direction === "previous"
+ ? -(program.spec.visibility.previous + 1)
+ : program.spec.visibility.next + 1;
+ return { ...resolveDepthStackPose(program.spec, depth), opacity: 0 };
+}
+
+function poseAnimation(input: {
+ readonly program: DepthStackProgram;
+ readonly stageDuration: number;
+ readonly oldDepth?: number;
+ readonly newDepth?: number;
+}): VisualAnimation | undefined {
+ if (input.newDepth === undefined && input.oldDepth === undefined) return undefined;
+ if (input.program.spec.reflow.durationFrames === 0) return undefined;
+ const oldPose = input.oldDepth === undefined
+ ? hiddenPose(input.program, input.newDepth === 0 || input.newDepth! > 0 ? "next" : "previous")
+ : resolveDepthStackPose(input.program.spec, input.oldDepth);
+ const newPose = input.newDepth === undefined
+ ? hiddenPose(input.program, input.oldDepth === 0 || input.oldDepth! < 0 ? "previous" : "next")
+ : resolveDepthStackPose(input.program.spec, input.newDepth);
+ const duration = input.program.spec.reflow.durationFrames;
+ const keyframes = [
+ { atFrame: 0, easing: input.program.spec.reflow.easing, style: poseStyle(oldPose) },
+ { atFrame: duration, style: poseStyle(newPose) },
+ ];
+ if (duration < input.stageDuration) keyframes.push({ atFrame: input.stageDuration, style: poseStyle(newPose) });
+ return { keyframes };
+}
+
+function rootBox(id: string, parent: string | undefined, order: number, style: VisualStyleDeclaration[], animation?: VisualAnimation): VisualElement {
+ return {
+ id,
+ ...(parent === undefined ? {} : { parent }),
+ order,
+ kind: "box",
+ style,
+ ...(animation === undefined ? {} : { animation }),
+ };
+}
+
+function rational(numerator: number, denominator = 1) {
+ return { numerator, denominator };
+}
+
+function modulo(value: number, size: number): number {
+ return ((value % size) + size) % size;
+}
+
+function sourceTiming(layer: MediaSampleLayerProgram): {
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
+ readonly frameCount: number;
+} | undefined {
+ if (layer.source.kind === "timed") {
+ return { frameRate: layer.source.frameRate, frameCount: layer.source.frameCount };
+ }
+ if (layer.source.kind === "surface" && layer.source.surface.timing.kind === "frames") {
+ return {
+ frameRate: layer.source.surface.timing.frameRate,
+ frameCount: layer.source.surface.timing.frameCount,
+ };
+ }
+ return undefined;
+}
+
+function trimFor(layer: MediaSampleLayerProgram, frameCount: number): MediaVisualTrim {
+ return layer.trim ?? { startFrame: 0, endFrameExclusive: frameCount };
+}
+
+function heldSampling(
+ timing: NonNullable<ReturnType<typeof sourceTiming>>,
+ targetFrames: number,
+ sourceFrame: number,
+): VisualTimedSampling {
+ return {
+ sourceFrameRate: { ...timing.frameRate },
+ sourceFrameCount: timing.frameCount,
+ segments: [{
+ target: { startFrame: 0, endFrameExclusive: targetFrames },
+ sourceFrame: rational(sourceFrame),
+ rate: rational(0),
+ }],
+ };
+}
+
+function continuedSampling(input: {
+ readonly timing: NonNullable<ReturnType<typeof sourceTiming>>;
+ readonly trim: MediaVisualTrim;
+ readonly targetFrames: number;
+ readonly absoluteStart: number;
+ readonly activationFrame: number;
+}): VisualTimedSampling {
+ const length = input.trim.endFrameExclusive - input.trim.startFrame;
+ const phase = modulo(input.absoluteStart - input.activationFrame, length);
+ return {
+ sourceFrameRate: { ...input.timing.frameRate },
+ sourceFrameCount: input.timing.frameCount,
+ segments: [{
+ target: { startFrame: 0, endFrameExclusive: input.targetFrames },
+ sourceFrame: rational(input.trim.startFrame + phase),
+ rate: rational(1),
+ loop: { ...input.trim },
+ }],
+ };
+}
+
+function samplingFor(input: {
+ readonly program: DepthStackProgram;
+ readonly card: DepthStackCard;
+ readonly layer: MediaSampleLayerProgram;
+ readonly relation: number;
+ readonly stageStart: number;
+ readonly stageDuration: number;
+ readonly space: ProgramSpace;
+}): VisualTimedSampling | undefined {
+ const timing = sourceTiming(input.layer);
+ if (timing === undefined) return undefined;
+ assert(timing.frameRate.numerator === input.space.frameRate.numerator
+ && timing.frameRate.denominator === input.space.frameRate.denominator,
+ `DepthStack Card ${input.card.id} timed material must be normalized to ProgramSpace.`);
+ const trim = trimFor(input.layer, timing.frameCount);
+ if (input.relation === 0) {
+ return resolveVisualSampling({
+ space: input.space,
+ sourceFrameRate: timing.frameRate,
+ sourceFrameCount: timing.frameCount,
+ targetFrameCount: input.stageDuration,
+ trim,
+ occupancy: input.layer.occupancy!,
+ });
+ }
+ const mode = input.relation > 0 ? input.card.playback.future : input.card.playback.past;
+ if (mode === "continue") {
+ assert(input.layer.occupancy?.mode === "loop" && input.layer.occupancy.align === "start",
+ `DepthStack Card ${input.card.id} continue playback requires loop-start active occupancy.`);
+ return continuedSampling({
+ timing,
+ trim,
+ targetFrames: input.stageDuration,
+ absoluteStart: input.stageStart,
+ activationFrame: input.card.activationFrame,
+ });
+ }
+ return heldSampling(
+ timing,
+ input.stageDuration,
+ mode === "hold-tail" ? trim.endFrameExclusive - 1 : trim.startFrame,
+ );
+}
+
+function groupElements(input: {
+ readonly program: DepthStackProgram;
+ readonly stageStart: number;
+ readonly stageEnd: number;
+ readonly pose: DepthStackPose;
+ readonly poseAnimation?: VisualAnimation;
+}): { readonly elements: VisualElement[]; readonly poseParent: string } {
+ const frame = input.program.frame;
+ const duration = input.program.span.endFrameExclusive - input.program.span.startFrame;
+ const startOffset = input.stageStart - input.program.span.startFrame;
+ const endOffset = input.stageEnd - input.program.span.startFrame;
+ let order = 0;
+ const elements: VisualElement[] = [rootBox("deck-placement", undefined, order++, [
+ { name: "height", value: px(frame.heightPx) },
+ { name: "left", value: px(frame.xPx) },
+ { name: "position", value: "absolute" },
+ { name: "top", value: px(frame.yPx) },
+ { name: "width", value: px(frame.widthPx) },
+ ])];
+ let parent = "deck-placement";
+ const lifecycle = lifecycleAnimationWindow(input.program.spec.motion, duration, startOffset, endOffset);
+ elements.push(rootBox("deck-lifecycle", parent, order++, [
+ { name: "height", value: "100%" },
+ { name: "position", value: "absolute" },
+ { name: "transform-origin", value: "center center" },
+ { name: "width", value: "100%" },
+ ], lifecycle));
+ parent = "deck-lifecycle";
+ for (const [index, sustain] of input.program.spec.motion.sustain.entries()) {
+ const id = `deck-sustain-${index + 1}`;
+ elements.push(rootBox(id, parent, order++, [
+ { name: "height", value: "100%" },
+ { name: "position", value: "absolute" },
+ { name: "transform-origin", value: "center center" },
+ { name: "width", value: "100%" },
+ ], sustainAnimationWindow(sustain, duration, startOffset, endOffset)));
+ parent = id;
+ }
+ elements.push(rootBox("deck-pose", parent, order++, [
+ { name: "height", value: "100%" },
+ { name: "position", value: "absolute" },
+ { name: "transform-origin", value: "center center" },
+ { name: "width", value: "100%" },
+ ...poseStyle(input.pose),
+ ], input.poseAnimation));
+ return { elements, poseParent: "deck-pose" };
+}
+
+function localFrame(frame: SpatialFrame): SpatialFrame {
+ return {
+ contract: "svml.spatial-frame@1",
+ xPx: 0,
+ yPx: 0,
+ widthPx: frame.widthPx,
+ heightPx: frame.heightPx,
+ };
+}
+
+function labelElement(card: DepthStackCard, parent: string, order: number): VisualElement | undefined {
+ if (card.label.kind === "none") return undefined;
+ return {
+ id: "deck-label",
+ parent,
+ order,
+ kind: "text-flow",
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ document: structuredClone(card.label.document),
+ typography: structuredClone(card.label.typography),
+ paints: structuredClone(card.label.paints),
+ flow: structuredClone(card.label.flow),
+ sequences: [],
+ };
+}
+
+export function renderDepthStack(
+ canvas: CanvasSpace,
+ space: ProgramSpace,
+ program: DepthStackProgram,
+): VisualTrack {
+ assertDepthStackProgramIdentity(program, space);
+ assert(canvas.contract === "svml.canvas-space@1", "DepthStack CanvasSpace is invalid.");
+ const presents: VisualTrack["presents"][number][] = [];
+ for (let stageIndex = 0; stageIndex < program.cards.length; stageIndex += 1) {
+ const stageStart = program.cards[stageIndex]!.activationFrame;
+ const stageEnd = program.cards[stageIndex + 1]?.activationFrame ?? program.terminalFrame;
+ const stageDuration = stageEnd - stageStart;
+ const oldState = stageIndex === 0 ? new Map<number, number>() : resolveDepthStackState(program, stageIndex - 1);
+ const newState = resolveDepthStackState(program, stageIndex);
+ const cardIndices = stageIndex === 0 || program.spec.reflow.durationFrames === 0
+ ? [...newState.keys()]
+ : [...new Set([...oldState.keys(), ...newState.keys()])];
+ for (const cardIndex of cardIndices) {
+ const card = program.cards[cardIndex]!;
+ const oldDepth = oldState.get(cardIndex);
+ const newDepth = newState.get(cardIndex);
+ const staticPose = newDepth === undefined
+ ? hiddenPose(program, oldDepth === 0 || (oldDepth ?? -1) < 0 ? "previous" : "next")
+ : resolveDepthStackPose(program.spec, newDepth);
+ const animation = stageIndex === 0 ? undefined : poseAnimation({
+ program,
+ stageDuration,
+ ...(oldDepth === undefined ? {} : { oldDepth }),
+ ...(newDepth === undefined ? {} : { newDepth }),
+ });
+ const group = groupElements({
+ program,
+ stageStart,
+ stageEnd,
+ pose: staticPose,
+ ...(animation === undefined ? {} : { poseAnimation: animation }),
+ });
+ const relation = newDepth ?? (oldDepth === 0 ? -1 : oldDepth ?? 1);
+ const samplingOverrides: Record<string, VisualTimedSampling> = {};
+ const samplingAnimationOverrides: Record<string, VisualAnimation | null> = {};
+ for (const layer of card.material.layers) {
+ if (layer.kind !== "sample") continue;
+ const sampling = samplingFor({ program, card, layer, relation, stageStart, stageDuration, space });
+ if (sampling !== undefined) samplingOverrides[layer.id] = sampling;
+ if (relation !== 0 && layer.samplingMotion !== undefined) samplingAnimationOverrides[layer.id] = null;
+ }
+ const mediaItem: MediaItemProgram = {
+ id: "deck-material",
+ sourceOccurrenceId: card.id,
+ span: { startFrame: stageStart, endFrameExclusive: stageEnd },
+ frame: localFrame(program.frame),
+ presentation: structuredClone(program.spec.presentation),
+ layers: structuredClone(card.material.layers),
+ motion: { sustain: [] },
+ stacking: { order: 0, tieBreak: card.id },
+ sounds: [],
+ };
+ const material = [...lowerMediaItemElements(mediaItem, space, {
+ placementParent: group.poseParent,
+ lifecycleAnimationOverride: null,
+ samplingOverrides,
+ samplingAnimationOverrides,
+ })].map((element) => ({ ...element, order: element.order + group.elements.length }));
+ const frameId = `${mediaItem.id}:frame`;
+ const label = labelElement(card, frameId, material.reduce((maximum, element) => Math.max(maximum, element.order), 0) + 1);
+ presents.push({
+ id: `${card.id}:stage:${stageIndex + 1}`,
+ span: { startFrame: stageStart, endFrameExclusive: stageEnd },
+ stacking: {
+ order: program.spec.stackingOrder + (newDepth === undefined
+ ? resolveDepthStackPose(program.spec, oldDepth ?? 0).stacking
+ : resolveDepthStackPose(program.spec, newDepth).stacking),
+ tieBreak: `${program.id}:${String(stageIndex).padStart(4, "0")}:${card.id}`,
+ },
+ elements: [...group.elements, ...material, ...(label === undefined ? [] : [label])],
+ });
+ }
+ }
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ visualIr: "svml.visual-ir@1",
+ id: program.id,
+ presents,
+ });
+ assertVisualTrackIdentity(track, space);
+ return track;
+}
diff --git a/packages/deck-track/src/manifest.ts b/packages/deck-track/src/manifest.ts
new file mode 100644
index 00000000..448bc4b2
--- /dev/null
+++ b/packages/deck-track/src/manifest.ts
@@ -0,0 +1,156 @@
+import {
+ compositionDependency,
+ compositionTypes,
+ visualTextDocumentSchema,
+ visualTextFlowSchema,
+ visualTextPaintSchema,
+ visualTextTypographySchema,
+} from "@narratage/composition";
+import { mediaDependency } from "@narratage/media";
+import {
+ mediaFramePresentationSchema,
+ mediaLayerSetSchema,
+ mediaLifecycleMotionSchema,
+ mediaTrackDependency,
+ mediaTrackTypes,
+} from "@narratage/media-track";
+import { narrativeDependency, narrativeTypes } from "@narratage/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@narratage/program-space";
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
+import { semanticMapDependency, semanticMapTypes } from "@narratage/semantic-map";
+import { spatialDependency, spatialFrameSchema, spatialTypes } from "@narratage/spatial";
+import { temporalDependency } from "@narratage/temporal";
+
+import { depthStackImplementationDigests, depthStackValidatorDigests } from "./program.js";
+
+export const depthStackModuleRef = { name: "@narratage/deck-track", version: "0.0.0-dev" } as const;
+export const depthStackTypes = {
+ header: { module: depthStackModuleRef, name: "DepthStackHeader" },
+ spec: { module: depthStackModuleRef, name: "DepthStackSpec" },
+ cardSpec: { module: depthStackModuleRef, name: "DepthStackCardSpec" },
+ cardLabel: { module: depthStackModuleRef, name: "DepthStackCardLabel" },
+ cardSet: { module: depthStackModuleRef, name: "DepthStackCardSet" },
+ program: { module: depthStackModuleRef, name: "DepthStackProgram" },
+} satisfies Record<string, TypeRef>;
+export const depthStackProducers = {
+ createCards: { module: depthStackModuleRef, name: "create-depth-stack-card-set" },
+ appendMomentCard: { module: depthStackModuleRef, name: "append-depth-stack-moment-card" },
+ finalizeProgramEnd: { module: depthStackModuleRef, name: "finalize-depth-stack-at-program-end" },
+ finalizeUntilMoment: { module: depthStackModuleRef, name: "finalize-depth-stack-until-moment" },
+ finalizeUntilSelectionStart: { module: depthStackModuleRef, name: "finalize-depth-stack-until-selection-start" },
+ finalizeUntilSelectionEnd: { module: depthStackModuleRef, name: "finalize-depth-stack-until-selection-end" },
+ render: { module: depthStackModuleRef, name: "render-depth-stack" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const positive = { kind: "number", minimum: 0.000001 } as const;
+const integer = { kind: "number", integer: true } as const;
+const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const enumString = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
+const tone = object({ brightness: { schema: positive }, contrast: { schema: positive }, saturation: { schema: positive } });
+const pose = object({
+ xPx: { schema: number }, yPx: { schema: number }, scale: { schema: positive }, rotationDeg: { schema: number },
+ opacity: { schema: { kind: "number", minimum: 0, maximum: 1 } }, stacking: { schema: integer }, tone: { schema: tone },
+});
+const poseStep = object({
+ xPerDepthPx: { schema: number }, yPerDepthPx: { schema: number }, scalePerDepth: { schema: positive },
+ rotationPerDepthDeg: { schema: number }, rotationMode: { schema: enumString(["linear", "alternate"]) },
+ opacityPerDepth: { schema: { kind: "number", minimum: 0, maximum: 1 } }, stackingPerDepth: { schema: integer },
+ tonePerDepth: { schema: tone },
+});
+const playback = object({
+ future: { schema: enumString(["hold-head", "continue"]) },
+ past: { schema: enumString(["hold-tail", "continue", "hide"]) },
+});
+
+export const depthStackSpecSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-spec@1" } },
+ visibility: { schema: object({ previous: { schema: unsignedInteger }, next: { schema: unsignedInteger }, wrap: { schema: { kind: "boolean" } } }) },
+ poses: { schema: object({ current: { schema: pose }, previous: { schema: poseStep }, next: { schema: poseStep } }) },
+ reflow: { schema: object({ durationFrames: { schema: unsignedInteger }, easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]) } }) },
+ presentation: { schema: mediaFramePresentationSchema }, motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
+});
+export const depthStackCardSpecSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-card-spec@1" } }, id: { schema: string }, playback: { schema: playback },
+});
+export const depthStackCardLabelSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ contract: { schema: { kind: "literal", value: "svml.depth-stack-card-label@1" } }, kind: { schema: { kind: "literal", value: "none" } } }),
+ object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-card-label@1" } }, kind: { schema: { kind: "literal", value: "text" } },
+ document: { schema: visualTextDocumentSchema }, typography: { schema: visualTextTypographySchema },
+ paints: { schema: { kind: "array", items: visualTextPaintSchema } }, flow: { schema: visualTextFlowSchema },
+ }),
+] };
+const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: positiveInteger } });
+const card = object({
+ id: { schema: string }, activationFrame: { schema: unsignedInteger }, material: { schema: mediaLayerSetSchema },
+ label: { schema: depthStackCardLabelSchema }, playback: { schema: playback },
+});
+export const depthStackHeaderSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-header@1" } }, id: { schema: string },
+});
+export const depthStackCardSetSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-card-set@1" } }, cards: { schema: { kind: "array", items: card } },
+});
+export const depthStackProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.depth-stack-program@1" } }, id: { schema: string }, span: { schema: frameSpan },
+ terminalFrame: { schema: positiveInteger }, frame: { schema: spatialFrameSchema }, spec: { schema: depthStackSpecSchema },
+ cards: { schema: { kind: "array", minItems: 1, items: card } },
+});
+
+export const depthStackSurfaceImplementationDigests = {
+ label: digestOf("@narratage/deck-track/label-surface@1"),
+ track: digestOf("@narratage/deck-track/depth-stack-surface@1"),
+} as const;
+const registered = (locator: string, digest: ReturnType<typeof digestOf>) => ({ kind: "registered" as const, locator, digest });
+const validator = (locator: string, digest: ReturnType<typeof digestOf>) => ({ abi: "svml.type-validator@1" as const, implementation: registered(locator, digest) });
+const finalizeInputs = [
+ { name: "set", type: depthStackTypes.cardSet }, { name: "header", type: depthStackTypes.header },
+ { name: "frame", type: spatialTypes.frame }, { name: "spec", type: depthStackTypes.spec },
+ { name: "space", type: programSpaceTypes.programSpace },
+] as const;
+
+export const depthStackManifest: ModuleManifest = {
+ format: "svml.module@1", name: depthStackModuleRef.name, version: depthStackModuleRef.version,
+ dependencies: [narrativeDependency, semanticMapDependency, programSpaceDependency, spatialDependency, temporalDependency, mediaDependency, mediaTrackDependency, compositionDependency],
+ types: [
+ { name: depthStackTypes.header.name, schema: depthStackHeaderSchema },
+ { name: depthStackTypes.spec.name, schema: depthStackSpecSchema },
+ { name: depthStackTypes.cardSpec.name, schema: depthStackCardSpecSchema },
+ { name: depthStackTypes.cardLabel.name, schema: depthStackCardLabelSchema },
+ { name: depthStackTypes.cardSet.name, schema: depthStackCardSetSchema },
+ { name: depthStackTypes.program.name, schema: depthStackProgramSchema, validator: validator("@narratage/deck-track/validate-program", depthStackValidatorDigests.program) },
+ ], capabilities: [],
+ surfaces: [
+ { name: "label", tag: "Label", mode: "structured", outputs: [depthStackTypes.cardLabel], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/deck-track/label-surface", digest: depthStackSurfaceImplementationDigests.label } },
+ { name: "track", tag: "DepthStack", mode: "structured", outputs: [depthStackTypes.header, depthStackTypes.spec, depthStackTypes.cardSpec, depthStackTypes.program, compositionTypes.visualTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/deck-track/depth-stack-surface", digest: depthStackSurfaceImplementationDigests.track } },
+ ],
+ producers: [
+ { name: depthStackProducers.createCards.name, inputs: [], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [], implementation: registered("@narratage/deck-track/create-cards", depthStackImplementationDigests.createCards) },
+ { name: depthStackProducers.appendMomentCard.name, inputs: [
+ { name: "set", type: depthStackTypes.cardSet }, { name: "material", type: mediaTrackTypes.layerSet },
+ { name: "label", type: depthStackTypes.cardLabel }, { name: "spec", type: depthStackTypes.cardSpec },
+ { name: "map", type: semanticMapTypes.complete }, { name: "moment", type: narrativeTypes.moment },
+ { name: "space", type: programSpaceTypes.programSpace },
+ ], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [], implementation: registered("@narratage/deck-track/append-moment-card", depthStackImplementationDigests.appendMomentCard) },
+ { name: depthStackProducers.finalizeProgramEnd.name, inputs: finalizeInputs, outputs: [{ name: "program", type: depthStackTypes.program }], needs: [], implementation: registered("@narratage/deck-track/finalize-program-end", depthStackImplementationDigests.finalizeProgramEnd) },
+ ...([
+ [depthStackProducers.finalizeUntilMoment, narrativeTypes.moment, depthStackImplementationDigests.finalizeUntilMoment, "@narratage/deck-track/finalize-until-moment"],
+ [depthStackProducers.finalizeUntilSelectionStart, narrativeTypes.selection, depthStackImplementationDigests.finalizeUntilSelectionStart, "@narratage/deck-track/finalize-until-selection-start"],
+ [depthStackProducers.finalizeUntilSelectionEnd, narrativeTypes.selection, depthStackImplementationDigests.finalizeUntilSelectionEnd, "@narratage/deck-track/finalize-until-selection-end"],
+ ] as const).map(([producer, terminalType, implementationDigest, locator]) => ({
+ name: producer.name, inputs: [...finalizeInputs, { name: "map", type: semanticMapTypes.complete }, { name: "terminal", type: terminalType }],
+ outputs: [{ name: "program", type: depthStackTypes.program }], needs: [], implementation: registered(locator, implementationDigest),
+ })),
+ { name: depthStackProducers.render.name, inputs: [
+ { name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace },
+ { name: "program", type: depthStackTypes.program },
+ ], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [], implementation: registered("@narratage/deck-track/render", depthStackImplementationDigests.render) },
+ ],
+};
+export const depthStackManifestDigest = digestOf(depthStackManifest);
+export const depthStackDependency = { module: depthStackModuleRef, digest: depthStackManifestDigest } as const;
diff --git a/packages/deck-track/src/program.ts b/packages/deck-track/src/program.ts
new file mode 100644
index 00000000..e5748e6f
--- /dev/null
+++ b/packages/deck-track/src/program.ts
@@ -0,0 +1,410 @@
+import type { VisualTrack } from "@narratage/composition";
+import {
+ assertFontArtifactRef,
+} from "@narratage/media";
+import {
+ assertMediaFramePresentation,
+ assertMediaLayerSet,
+ assertMediaLifecycleMotion,
+} from "@narratage/media-track";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import {
+ assertProgramSpaceIdentity,
+ programSpaceFrameCount,
+} from "@narratage/program-space";
+import type { ProgramSpace } from "@narratage/program-space";
+import { canonicalize, digestOf } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import { assertSpatialFrame } from "@narratage/spatial";
+import type { SpatialFrame } from "@narratage/spatial";
+import {
+ locateMomentOccurrences,
+ locateSelectionOccurrences,
+} from "@narratage/temporal";
+
+import type {
+ DeckCardTone,
+ DepthStackCardLabel,
+ DepthStackCardSet,
+ DepthStackCardSpec,
+ DepthStackHeader,
+ DepthStackPose,
+ DepthStackPoseStep,
+ DepthStackProgram,
+ DepthStackSpec,
+ DepthStackState,
+} from "./types.js";
+
+export const depthStackImplementationDigests = {
+ createCards: digestOf("@narratage/deck-track/create-cards@1"),
+ appendMomentCard: digestOf("@narratage/deck-track/append-moment-card@1"),
+ finalizeProgramEnd: digestOf("@narratage/deck-track/finalize-program-end@1"),
+ finalizeUntilMoment: digestOf("@narratage/deck-track/finalize-until-moment@1"),
+ finalizeUntilSelectionStart: digestOf("@narratage/deck-track/finalize-until-selection-start@1"),
+ finalizeUntilSelectionEnd: digestOf("@narratage/deck-track/finalize-until-selection-end@1"),
+ render: digestOf("@narratage/deck-track/render-depth-stack@1"),
+} as const;
+
+export const depthStackValidatorDigests = {
+ program: digestOf("@narratage/deck-track/validate-program@1"),
+} as const;
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function identity(value: string, label: string): void {
+ assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+
+function finite(value: number, label: string): void {
+ assert(Number.isFinite(value), `${label} must be finite.`);
+}
+
+function unit(value: number, label: string): void {
+ finite(value, label);
+ assert(value >= 0 && value <= 1, `${label} must be inside [0, 1].`);
+}
+
+function positive(value: number, label: string): void {
+ finite(value, label);
+ assert(value > 0, `${label} must be positive.`);
+}
+
+function assertTone(value: DeckCardTone, label: string): void {
+ positive(value.brightness, `${label}.brightness`);
+ positive(value.contrast, `${label}.contrast`);
+ positive(value.saturation, `${label}.saturation`);
+}
+
+function assertPose(value: DepthStackPose, label: string): void {
+ finite(value.xPx, `${label}.xPx`);
+ finite(value.yPx, `${label}.yPx`);
+ positive(value.scale, `${label}.scale`);
+ finite(value.rotationDeg, `${label}.rotationDeg`);
+ unit(value.opacity, `${label}.opacity`);
+ assert(Number.isSafeInteger(value.stacking), `${label}.stacking must be an integer.`);
+ assertTone(value.tone, `${label}.tone`);
+}
+
+function assertPoseStep(value: DepthStackPoseStep, label: string): void {
+ finite(value.xPerDepthPx, `${label}.xPerDepthPx`);
+ finite(value.yPerDepthPx, `${label}.yPerDepthPx`);
+ positive(value.scalePerDepth, `${label}.scalePerDepth`);
+ finite(value.rotationPerDepthDeg, `${label}.rotationPerDepthDeg`);
+ assert(value.rotationMode === "linear" || value.rotationMode === "alternate", `${label}.rotationMode is invalid.`);
+ unit(value.opacityPerDepth, `${label}.opacityPerDepth`);
+ assert(Number.isSafeInteger(value.stackingPerDepth), `${label}.stackingPerDepth must be an integer.`);
+ assertTone(value.tonePerDepth, `${label}.tonePerDepth`);
+}
+
+export function assertDepthStackSpec(value: DepthStackSpec): void {
+ assert(value.contract === "svml.depth-stack-spec@1", "Unsupported DepthStackSpec contract.");
+ for (const [name, count] of Object.entries(value.visibility)) {
+ if (name === "wrap") continue;
+ assert(Number.isSafeInteger(count) && typeof count === "number" && count >= 0 && count <= 1_000,
+ `DepthStackSpec.visibility.${name} is invalid.`);
+ }
+ assert(typeof value.visibility.wrap === "boolean", "DepthStackSpec.visibility.wrap is invalid.");
+ assertPose(value.poses.current, "DepthStackSpec.poses.current");
+ assertPoseStep(value.poses.previous, "DepthStackSpec.poses.previous");
+ assertPoseStep(value.poses.next, "DepthStackSpec.poses.next");
+ assert(Number.isSafeInteger(value.reflow.durationFrames) && value.reflow.durationFrames >= 0,
+ "DepthStackSpec.reflow.durationFrames must be a non-negative integer.");
+ assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.reflow.easing),
+ "DepthStackSpec.reflow.easing is invalid.");
+ assertMediaFramePresentation(value.presentation, "DepthStackSpec.presentation");
+ assert(Number.isSafeInteger(value.stackingOrder), "DepthStackSpec.stackingOrder must be an integer.");
+}
+
+export function sealDepthStackSpec(value: DepthStackSpec): DepthStackSpec {
+ assertDepthStackSpec(value);
+ return canonicalize(value) as unknown as DepthStackSpec;
+}
+
+export function assertDepthStackCardLabel(value: DepthStackCardLabel): void {
+ assert(value.contract === "svml.depth-stack-card-label@1", "Unsupported DepthStackCardLabel contract.");
+ if (value.kind === "none") return;
+ assert(value.kind === "text", "DepthStackCardLabel kind is invalid.");
+ assert(value.document.paragraphs.length > 0, "DepthStackCardLabel document is empty.");
+ const fonts = value.typography.fonts;
+ assert(fonts !== undefined && fonts.length > 0 && value.typography.prototypeFamily === undefined,
+ "DepthStackCardLabel requires exact font Artifacts.");
+ for (const [index, font] of fonts.entries()) assertFontArtifactRef(font, `DepthStackCardLabel.fonts.${index}`);
+ assert(value.typography.synthesis === "none", "DepthStackCardLabel cannot synthesize an exact font.");
+ assert(value.flow.form.kind === "area", "DepthStackCardLabel uses Area flow inside its Card.");
+}
+
+export function sealDepthStackCardLabel(value: DepthStackCardLabel): DepthStackCardLabel {
+ assertDepthStackCardLabel(value);
+ return canonicalize(value) as unknown as DepthStackCardLabel;
+}
+
+export const noDepthStackCardLabel = (): DepthStackCardLabel => ({
+ contract: "svml.depth-stack-card-label@1",
+ kind: "none",
+});
+
+export function assertDepthStackCardSpec(value: DepthStackCardSpec): void {
+ assert(value.contract === "svml.depth-stack-card-spec@1", "Unsupported DepthStackCardSpec contract.");
+ identity(value.id, "DepthStackCardSpec.id");
+ assert(value.playback.future === "hold-head" || value.playback.future === "continue",
+ "DepthStackCardSpec.playback.future is invalid.");
+ assert(["hold-tail", "continue", "hide"].includes(value.playback.past),
+ "DepthStackCardSpec.playback.past is invalid.");
+}
+
+export function sealDepthStackCardSpec(value: DepthStackCardSpec): DepthStackCardSpec {
+ assertDepthStackCardSpec(value);
+ return canonicalize(value) as unknown as DepthStackCardSpec;
+}
+
+export function assertDepthStackHeader(value: DepthStackHeader): void {
+ assert(value.contract === "svml.depth-stack-header@1", "Unsupported DepthStackHeader contract.");
+ identity(value.id, "DepthStackHeader.id");
+}
+
+export function sealDepthStackHeader(value: DepthStackHeader): DepthStackHeader {
+ assertDepthStackHeader(value);
+ return canonicalize(value) as unknown as DepthStackHeader;
+}
+
+export function createDepthStackCardSet(): DepthStackCardSet {
+ return { contract: "svml.depth-stack-card-set@1", cards: [] };
+}
+
+export function assertDepthStackCardSet(value: DepthStackCardSet): void {
+ assert(value.contract === "svml.depth-stack-card-set@1" && Array.isArray(value.cards),
+ "DepthStackCardSet is invalid.");
+ const ids = new Set<string>();
+ let previous = -1;
+ for (const card of value.cards) {
+ identity(card.id, "DepthStack Card id");
+ assert(!ids.has(card.id), `DepthStackCardSet repeats ${card.id}.`);
+ ids.add(card.id);
+ assert(Number.isSafeInteger(card.activationFrame) && card.activationFrame >= 0,
+ `DepthStack Card ${card.id} activation is invalid.`);
+ assert(card.activationFrame > previous, "DepthStack Card triggers must be strictly increasing in authored order.");
+ previous = card.activationFrame;
+ assertMediaLayerSet(card.material);
+ assert(card.material.layers.length > 0, `DepthStack Card ${card.id} material is empty.`);
+ assertDepthStackCardLabel(card.label);
+ assertDepthStackCardSpec({ contract: "svml.depth-stack-card-spec@1", id: card.id, playback: card.playback });
+ }
+}
+
+export function appendDepthStackCard(
+ set: DepthStackCardSet,
+ material: DepthStackCardSet["cards"][number]["material"],
+ label: DepthStackCardLabel,
+ spec: DepthStackCardSpec,
+ activationFrame: number,
+): DepthStackCardSet {
+ assertDepthStackCardSet(set);
+ assertMediaLayerSet(material);
+ assert(material.layers.length > 0, `DepthStack Card ${spec.id} material is empty.`);
+ assertDepthStackCardLabel(label);
+ assertDepthStackCardSpec(spec);
+ assert(Number.isSafeInteger(activationFrame) && activationFrame >= 0,
+ `DepthStack Card ${spec.id} activation is invalid.`);
+ const result: DepthStackCardSet = {
+ contract: "svml.depth-stack-card-set@1",
+ cards: [...set.cards, {
+ id: spec.id,
+ activationFrame,
+ material: structuredClone(material),
+ label: structuredClone(label),
+ playback: { ...spec.playback },
+ }],
+ };
+ assertDepthStackCardSet(result);
+ return canonicalize(result) as unknown as DepthStackCardSet;
+}
+
+export function appendDepthStackMomentCard(
+ set: DepthStackCardSet,
+ material: DepthStackCardSet["cards"][number]["material"],
+ label: DepthStackCardLabel,
+ spec: DepthStackCardSpec,
+ map: CompleteSemanticMap,
+ moment: NarrativeMomentRef,
+ space: ProgramSpace,
+): DepthStackCardSet {
+ const occurrences = locateMomentOccurrences(map, moment, space);
+ assert(occurrences.length === 1,
+ `DepthStack Card ${spec.id} Moment must locate exactly once; received ${occurrences.length}.`);
+ return appendDepthStackCard(set, material, label, spec, occurrences[0]!.cue.frame);
+}
+
+function terminalMoment(map: CompleteSemanticMap, moment: NarrativeMomentRef, space: ProgramSpace): number {
+ const occurrences = locateMomentOccurrences(map, moment, space);
+ assert(occurrences.length === 1,
+ `DepthStack terminal Moment must locate exactly once; received ${occurrences.length}.`);
+ return occurrences[0]!.cue.frame;
+}
+
+function terminalSelection(
+ map: CompleteSemanticMap,
+ selection: NarrativeSelectionRef,
+ space: ProgramSpace,
+ boundary: "start" | "end",
+): number {
+ const occurrences = locateSelectionOccurrences(map, selection, space);
+ assert(occurrences.length === 1,
+ `DepthStack terminal Selection must locate exactly once; received ${occurrences.length}.`);
+ return boundary === "start" ? occurrences[0]!.start.frame : occurrences[0]!.end.frame;
+}
+
+export function finalizeDepthStack(
+ set: DepthStackCardSet,
+ header: DepthStackHeader,
+ frame: SpatialFrame,
+ spec: DepthStackSpec,
+ terminalFrame: number,
+ space: ProgramSpace,
+): DepthStackProgram {
+ assertDepthStackCardSet(set);
+ assertDepthStackHeader(header);
+ assertSpatialFrame(frame);
+ assertDepthStackSpec(spec);
+ assertProgramSpaceIdentity(space);
+ assert(set.cards.length > 0, "DepthStack requires at least one Card.");
+ const first = set.cards[0]!;
+ const program: DepthStackProgram = {
+ contract: "svml.depth-stack-program@1",
+ id: header.id,
+ span: { startFrame: first.activationFrame, endFrameExclusive: terminalFrame },
+ terminalFrame,
+ frame: structuredClone(frame),
+ spec: structuredClone(spec),
+ cards: structuredClone(set.cards),
+ };
+ assertDepthStackProgramIdentity(program, space);
+ return canonicalize(program) as unknown as DepthStackProgram;
+}
+
+export function finalizeDepthStackAtProgramEnd(
+ set: DepthStackCardSet,
+ header: DepthStackHeader,
+ frame: SpatialFrame,
+ spec: DepthStackSpec,
+ space: ProgramSpace,
+): DepthStackProgram {
+ return finalizeDepthStack(set, header, frame, spec, programSpaceFrameCount(space), space);
+}
+
+export function finalizeDepthStackUntilMoment(
+ set: DepthStackCardSet,
+ header: DepthStackHeader,
+ frame: SpatialFrame,
+ spec: DepthStackSpec,
+ map: CompleteSemanticMap,
+ moment: NarrativeMomentRef,
+ space: ProgramSpace,
+): DepthStackProgram {
+ return finalizeDepthStack(set, header, frame, spec, terminalMoment(map, moment, space), space);
+}
+
+export function finalizeDepthStackUntilSelection(
+ set: DepthStackCardSet,
+ header: DepthStackHeader,
+ frame: SpatialFrame,
+ spec: DepthStackSpec,
+ map: CompleteSemanticMap,
+ selection: NarrativeSelectionRef,
+ boundary: "start" | "end",
+ space: ProgramSpace,
+): DepthStackProgram {
+ return finalizeDepthStack(set, header, frame, spec, terminalSelection(map, selection, space, boundary), space);
+}
+
+export function assertDepthStackProgram(program: DepthStackProgram): void {
+ assert(program.contract === "svml.depth-stack-program@1", "Unsupported DepthStackProgram contract.");
+ identity(program.id, "DepthStackProgram.id");
+ assertSpatialFrame(program.frame);
+ assertDepthStackSpec(program.spec);
+ const set = { contract: "svml.depth-stack-card-set@1", cards: program.cards } as const;
+ assertDepthStackCardSet(set);
+ assert(program.cards.length > 0, "DepthStackProgram has no Cards.");
+ assert(Number.isSafeInteger(program.terminalFrame) && program.terminalFrame > 0,
+ "DepthStack terminal is invalid.");
+ assert(program.span.startFrame === program.cards[0]!.activationFrame
+ && program.span.endFrameExclusive === program.terminalFrame,
+ "DepthStackProgram span disagrees with its Card triggers and terminal.");
+ assert(program.cards.at(-1)!.activationFrame < program.terminalFrame,
+ "DepthStack terminal must be after every Card trigger.");
+ if (program.spec.visibility.wrap) {
+ assert(program.spec.visibility.previous + program.spec.visibility.next + 1 <= program.cards.length,
+ "Wrapped DepthStack visibility would show one Card at several relative depths.");
+ }
+ const duration = program.terminalFrame - program.cards[0]!.activationFrame;
+ assertMediaLifecycleMotion(program.spec.motion, duration, "DepthStack whole-group motion");
+ for (let index = 1; index < program.cards.length; index += 1) {
+ const stageEnd = program.cards[index + 1]?.activationFrame ?? program.terminalFrame;
+ const stageDuration = stageEnd - program.cards[index]!.activationFrame;
+ assert(program.spec.reflow.durationFrames <= stageDuration,
+ `DepthStack reflow exceeds Card ${program.cards[index]!.id} stage.`);
+ }
+}
+
+export function assertDepthStackProgramIdentity(program: DepthStackProgram, space: ProgramSpace): void {
+ assertProgramSpaceIdentity(space);
+ assertDepthStackProgram(program);
+ assert(program.terminalFrame <= programSpaceFrameCount(space), "DepthStack terminal is outside ProgramSpace.");
+}
+
+function modulo(value: number, size: number): number {
+ return ((value % size) + size) % size;
+}
+
+/** Resolve one immutable collection state; no renderer or previous-frame memory participates. */
+export function resolveDepthStackState(program: DepthStackProgram, currentIndex: number): DepthStackState {
+ assert(Number.isSafeInteger(currentIndex) && currentIndex >= 0 && currentIndex < program.cards.length,
+ "DepthStack current index is invalid.");
+ const state = new Map<number, number>([[currentIndex, 0]]);
+ const add = (rawIndex: number, depth: number): void => {
+ const index = program.spec.visibility.wrap ? modulo(rawIndex, program.cards.length) : rawIndex;
+ if (index < 0 || index >= program.cards.length) return;
+ if (depth < 0 && program.cards[index]!.playback.past === "hide") return;
+ assert(!state.has(index), `DepthStack Card ${program.cards[index]!.id} occupies several relative depths.`);
+ state.set(index, depth);
+ };
+ for (let depth = 1; depth <= program.spec.visibility.previous; depth += 1) add(currentIndex - depth, -depth);
+ for (let depth = 1; depth <= program.spec.visibility.next; depth += 1) add(currentIndex + depth, depth);
+ return state;
+}
+
+function power(value: number, exponent: number): number {
+ return Math.round((value ** exponent) * 1_000_000) / 1_000_000;
+}
+
+function clean(value: number): number {
+ const rounded = Math.round(value * 1_000_000) / 1_000_000;
+ return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+export function resolveDepthStackPose(spec: DepthStackSpec, relativeDepth: number): DepthStackPose {
+ assertDepthStackSpec(spec);
+ assert(Number.isSafeInteger(relativeDepth), "DepthStack relative depth must be an integer.");
+ if (relativeDepth === 0) return structuredClone(spec.poses.current);
+ const magnitude = Math.abs(relativeDepth);
+ const step = relativeDepth < 0 ? spec.poses.previous : spec.poses.next;
+ const rotationFactor = step.rotationMode === "linear" ? magnitude : magnitude % 2 === 1 ? 1 : -1;
+ const current = spec.poses.current;
+ return {
+ xPx: clean(current.xPx + (step.xPerDepthPx * magnitude)),
+ yPx: clean(current.yPx + (step.yPerDepthPx * magnitude)),
+ scale: clean(current.scale * power(step.scalePerDepth, magnitude)),
+ rotationDeg: clean(current.rotationDeg + (step.rotationPerDepthDeg * rotationFactor)),
+ opacity: clean(current.opacity * power(step.opacityPerDepth, magnitude)),
+ stacking: current.stacking + (step.stackingPerDepth * magnitude),
+ tone: {
+ brightness: clean(current.tone.brightness * power(step.tonePerDepth.brightness, magnitude)),
+ contrast: clean(current.tone.contrast * power(step.tonePerDepth.contrast, magnitude)),
+ saturation: clean(current.tone.saturation * power(step.tonePerDepth.saturation, magnitude)),
+ },
+ };
+}
+
+/** Type-only declaration used by the Component package without importing its lowering body here. */
+export type DepthStackRenderer = (space: ProgramSpace, program: DepthStackProgram) => VisualTrack;
diff --git a/packages/deck-track/src/surface.ts b/packages/deck-track/src/surface.ts
new file mode 100644
index 00000000..9b105a5e
--- /dev/null
+++ b/packages/deck-track/src/surface.ts
@@ -0,0 +1,276 @@
+import { artifactTypes } from "@narratage/artifact";
+import { mediaTypes } from "@narratage/media";
+import type { FontStackRef } from "@narratage/media";
+import { mediaTrackTypes } from "@narratage/media-track";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes } from "@narratage/program-space";
+import type { TypeRef } from "@narratage/protocol";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { spatialTypes } from "@narratage/spatial";
+import { svsRecipeType } from "@narratage/svs";
+import type { SvsRecipe } from "@narratage/svs";
+import type {
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceRecordDraft,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+
+import {
+ decodeDepthStackCardSpec,
+ decodeDepthStackMaterial,
+ decodeDepthStackSpec,
+} from "./author.js";
+import {
+ createDepthStackFragment,
+} from "./fragment.js";
+import type {
+ DepthStackFragmentCard,
+ DepthStackFragmentTerminal,
+} from "./fragment.js";
+import { depthStackTypes } from "./manifest.js";
+import {
+ noDepthStackCardLabel,
+ sealDepthStackCardLabel,
+ sealDepthStackHeader,
+} from "./program.js";
+import type { DepthStackCardLabel } from "./types.js";
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function allowed(element: StructuredElement, names: readonly string[]): void {
+ const permit = new Set(names);
+ const unknown = Object.keys(element.attributes).filter((name) => !permit.has(name));
+ if (unknown.length > 0) throw new Error(`${element.name} has unsupported attributes ${unknown.join(", ")}.`);
+}
+
+function empty(element: StructuredElement): void {
+ if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+ throw new Error(`${element.name} must be empty.`);
+ }
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+ const value = element.attributes[name];
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
+ const value = element.attributes[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function numeric(element: StructuredElement, name: string, fallback: number): number {
+ const raw = optionalText(element, name);
+ if (raw === undefined) return fallback;
+ const value = Number(raw);
+ if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be numeric.`);
+ return value;
+}
+
+function reference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: TypeRef,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const value = resolve(raw.path);
+ if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`);
+ return value;
+}
+
+function oneOfReference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: readonly TypeRef[],
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const value = resolve(raw.path);
+ if (value === undefined || !expected.some((type) => sameType(value.type, type))) throw new Error(`${label} has the wrong Type.`);
+ return value;
+}
+
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+ if (value.record?.value.kind !== "inline") throw new Error(`${label} must resolve during author compilation.`);
+ return value.record.value.value as unknown as T;
+}
+
+function recipe(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SvsRecipe {
+ return inline<SvsRecipe>(reference(raw, label, svsRecipeType, resolve), label);
+}
+
+function labelText(element: StructuredElement): string {
+ if (element.children.some((child) => child.kind === "element")) throw new Error(`${element.name} accepts plain label text only.`);
+ const value = element.children.map((child) => child.kind === "text" ? child.value : "").join("").trim();
+ if (value.length === 0) throw new Error(`${element.name} label text is empty.`);
+ return value;
+}
+
+export const decodeDepthStackLabelSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "font", "size", "color", "align", "block", "padding"]);
+ const id = text(element, "id");
+ const stack = inline<FontStackRef>(reference(element.attributes.font, `${element.name}.font`, mediaTypes.fontStack, resolveReference), `${element.name}.font`);
+ const primary = stack.faces[0];
+ if (primary === undefined) throw new Error(`${element.name}.font stack is empty.`);
+ const align = text(element, "align", "center");
+ const block = text(element, "block", "end");
+ if (!["start", "center", "end", "justify"].includes(align)) throw new Error(`${element.name}.align is invalid.`);
+ if (!["start", "center", "end"].includes(block)) throw new Error(`${element.name}.block is invalid.`);
+ const padding = numeric(element, "padding", 20);
+ const value: DepthStackCardLabel = sealDepthStackCardLabel({
+ contract: "svml.depth-stack-card-label@1",
+ kind: "text",
+ document: { paragraphs: [{ id: `${id}:paragraph`, inlines: [{ kind: "text", id: `${id}:text`, text: labelText(element) }] }] },
+ typography: {
+ fonts: structuredClone(stack.faces), sizePx: numeric(element, "size", 34), weight: primary.weight, style: primary.style,
+ axes: [], features: [], synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+ lineHeight: 1.15, direction: "auto", writingMode: "horizontal-tb", baselineShiftPx: 0, tabSize: 4,
+ indentationPx: 0, paragraphBeforePx: 0, paragraphAfterPx: 0, transform: "none", variantCaps: "normal",
+ verticalAlign: "baseline", decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [{ kind: "fill", paint: { kind: "solid", color: text(element, "color", "#ffffff") } }],
+ flow: {
+ form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: padding, inlineEnd: padding, blockStart: padding, blockEnd: padding },
+ inlineAlign: align as "start" | "center" | "end" | "justify",
+ blockAlign: block as "start" | "center" | "end",
+ wrap: "word", overflow: "clip", clipToFrame: true, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ });
+ return {
+ records: [{ id, type: depthStackTypes.cardLabel, value: { kind: "inline", value }, range: element.range }],
+ components: [], fragments: [],
+ };
+};
+
+function terminal(
+ element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): { readonly terminal: DepthStackFragmentTerminal; readonly reference?: SurfaceResolvedReference } {
+ const raw = element.attributes.until;
+ if (typeof raw === "string") {
+ if (raw.trim() !== "program.end") throw new Error(`${element.name}.until text must be program.end.`);
+ if (element.attributes["until-boundary"] !== undefined) throw new Error(`${element.name}.until-boundary requires a Selection.`);
+ return { terminal: { kind: "program-end" } };
+ }
+ const value = oneOfReference(raw, `${element.name}.until`, [narrativeTypes.moment, narrativeTypes.selection], resolve);
+ if (sameType(value.type, narrativeTypes.moment)) {
+ if (element.attributes["until-boundary"] !== undefined) throw new Error(`${element.name}.until-boundary requires a Selection.`);
+ return { terminal: { kind: "moment", inputName: "terminal" }, reference: value };
+ }
+ const boundary = text(element, "until-boundary", "end");
+ if (boundary !== "start" && boundary !== "end") throw new Error(`${element.name}.until-boundary is invalid.`);
+ return { terminal: { kind: boundary === "start" ? "selection-start" : "selection-end", inputName: "terminal" }, reference: value };
+}
+
+export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "map", "space", "canvas", "frame", "appearance", "until", "until-boundary"]);
+ const id = text(element, "id");
+ const map = reference(element.attributes.map, `${element.name}.map`, semanticMapTypes.complete, resolveReference);
+ const space = reference(element.attributes.space, `${element.name}.space`, programSpaceTypes.programSpace, resolveReference);
+ const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+ const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
+ const appearance = recipe(element.attributes.appearance, `${element.name}.appearance`, resolveReference);
+ const terminalValue = terminal(element, resolveReference);
+ const records: SurfaceRecordDraft[] = [];
+ const headerId = `${id}.header`;
+ const specId = `${id}.spec`;
+ records.push(
+ { id: headerId, type: depthStackTypes.header, value: { kind: "inline", value: sealDepthStackHeader({ contract: "svml.depth-stack-header@1", id }) }, range: element.range },
+ { id: specId, type: depthStackTypes.spec, value: { kind: "inline", value: decodeDepthStackSpec(appearance) }, range: element.range },
+ );
+ const inputs: Record<string, typeof map.ref> = {
+ canvas: canvas.ref, frame: frame.ref, header: { kind: "record", id: headerId }, map: map.ref,
+ space: space.ref, spec: { kind: "record", id: specId },
+ };
+ if (terminalValue.reference !== undefined) inputs.terminal = terminalValue.reference.ref;
+ const cards: DepthStackFragmentCard[] = [];
+ let cardIndex = 0;
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts Card children only.`);
+ continue;
+ }
+ if (child.name.split(":").at(-1) !== "Card") throw new Error(`${element.name} accepts Card children only.`);
+ allowed(child, ["id", "source", "extent", "at", "appearance", "label"]);
+ empty(child);
+ cardIndex += 1;
+ const suffix = String(cardIndex).padStart(4, "0");
+ const cardId = text(child, "id");
+ const source = oneOfReference(child.attributes.source, `${child.name}.source`, [artifactTypes.blob, mediaTypes.synchronized, mediaTypes.compositableSurface], resolveReference);
+ const sourceKind = sameType(source.type, artifactTypes.blob) ? "still"
+ : sameType(source.type, mediaTypes.synchronized) ? "timed" : "surface";
+ const extent = child.attributes.extent === undefined ? undefined
+ : reference(child.attributes.extent, `${child.name}.extent`, spatialTypes.extent, resolveReference);
+ if (sourceKind === "still" && extent === undefined) throw new Error(`${child.name}.extent is required for a still image.`);
+ if (sourceKind !== "still" && extent !== undefined) throw new Error(`${child.name}.extent belongs only to a still image.`);
+ const moment = reference(child.attributes.at, `${child.name}.at`, narrativeTypes.moment, resolveReference);
+ const cardAppearance = child.attributes.appearance === undefined
+ ? appearance : recipe(child.attributes.appearance, `${child.name}.appearance`, resolveReference);
+ const material = decodeDepthStackMaterial(cardAppearance, `${id}.${cardId}`, sourceKind);
+ const fitId = `${id}.card.${suffix}.fit`;
+ const sampleId = `${id}.card.${suffix}.sample-spec`;
+ const cardSpecId = `${id}.card.${suffix}.card-spec`;
+ records.push(
+ { id: fitId, type: spatialTypes.fit, value: { kind: "inline", value: material.fit }, range: child.range },
+ { id: sampleId, type: mediaTrackTypes.sampleLayerSpec, value: { kind: "inline", value: material.sample }, range: child.range },
+ { id: cardSpecId, type: depthStackTypes.cardSpec, value: { kind: "inline", value: decodeDepthStackCardSpec(cardAppearance, cardId) }, range: child.range },
+ );
+ const sourceName = `card-${suffix}-source`;
+ const fitName = `card-${suffix}-fit`;
+ const sampleSpecName = `card-${suffix}-sample-spec`;
+ const cardSpecName = `card-${suffix}-spec`;
+ const momentName = `card-${suffix}-moment`;
+ const labelName = `card-${suffix}-label`;
+ inputs[sourceName] = source.ref;
+ inputs[fitName] = { kind: "record", id: fitId };
+ inputs[sampleSpecName] = { kind: "record", id: sampleId };
+ inputs[cardSpecName] = { kind: "record", id: cardSpecId };
+ inputs[momentName] = moment.ref;
+ let labelRef: typeof map.ref;
+ if (child.attributes.label === undefined) {
+ const labelId = `${id}.card.${suffix}.label-none`;
+ records.push({ id: labelId, type: depthStackTypes.cardLabel, value: { kind: "inline", value: noDepthStackCardLabel() }, range: child.range });
+ labelRef = { kind: "record", id: labelId };
+ } else {
+ labelRef = reference(child.attributes.label, `${child.name}.label`, depthStackTypes.cardLabel, resolveReference).ref;
+ }
+ inputs[labelName] = labelRef;
+ let extentName: string | undefined;
+ if (extent !== undefined) {
+ extentName = `card-${suffix}-extent`;
+ inputs[extentName] = extent.ref;
+ }
+ let framePaintSpecName: string | undefined;
+ if (material.framePaint !== undefined) {
+ framePaintSpecName = `card-${suffix}-frame-paint`;
+ const paintId = `${id}.card.${suffix}.frame-paint`;
+ records.push({ id: paintId, type: mediaTrackTypes.paintLayerSpec, value: { kind: "inline", value: material.framePaint }, range: child.range });
+ inputs[framePaintSpecName] = { kind: "record", id: paintId };
+ }
+ cards.push({
+ suffix, sourceKind, sourceName, ...(extentName === undefined ? {} : { extentName }), fitName, sampleSpecName,
+ ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, momentName,
+ });
+ }
+ if (cards.length === 0) throw new Error(`${element.name} requires at least one Card.`);
+ const fragment = createDepthStackFragment(cards, terminalValue.terminal, `@narratage/deck-track/surface/${id}@1`);
+ return {
+ records,
+ components: [{ id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],
+ fragments: [fragment],
+ };
+};
diff --git a/packages/deck-track/src/types.ts b/packages/deck-track/src/types.ts
new file mode 100644
index 00000000..2b54080d
--- /dev/null
+++ b/packages/deck-track/src/types.ts
@@ -0,0 +1,119 @@
+import type {
+ FrameSpan,
+ VisualTextDocument,
+ VisualTextFlow,
+ VisualTextPaintLayer,
+ VisualTextTypography,
+} from "@narratage/composition";
+import type {
+ MediaFramePresentation,
+ MediaLayerSet,
+ MediaLifecycleMotion,
+} from "@narratage/media-track";
+import type { SpatialFrame } from "@narratage/spatial";
+
+export type DepthStackVisibility = {
+ readonly previous: number;
+ readonly next: number;
+ readonly wrap: boolean;
+};
+
+export type DeckCardTone = {
+ readonly brightness: number;
+ readonly contrast: number;
+ readonly saturation: number;
+};
+
+export type DepthStackPose = {
+ readonly xPx: number;
+ readonly yPx: number;
+ readonly scale: number;
+ readonly rotationDeg: number;
+ readonly opacity: number;
+ readonly stacking: number;
+ readonly tone: DeckCardTone;
+};
+
+export type DepthStackPoseStep = {
+ readonly xPerDepthPx: number;
+ readonly yPerDepthPx: number;
+ readonly scalePerDepth: number;
+ readonly rotationPerDepthDeg: number;
+ readonly rotationMode: "linear" | "alternate";
+ readonly opacityPerDepth: number;
+ readonly stackingPerDepth: number;
+ readonly tonePerDepth: DeckCardTone;
+};
+
+export type DepthStackPoseModel = {
+ readonly current: DepthStackPose;
+ readonly previous: DepthStackPoseStep;
+ readonly next: DepthStackPoseStep;
+};
+
+export type DepthStackReflow = {
+ readonly durationFrames: number;
+ readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+};
+
+export type DepthStackSpec = {
+ readonly contract: "svml.depth-stack-spec@1";
+ readonly visibility: DepthStackVisibility;
+ readonly poses: DepthStackPoseModel;
+ readonly reflow: DepthStackReflow;
+ readonly presentation: MediaFramePresentation;
+ readonly motion: MediaLifecycleMotion;
+ readonly stackingOrder: number;
+};
+
+export type DepthStackCardPlayback = {
+ readonly future: "hold-head" | "continue";
+ readonly past: "hold-tail" | "continue" | "hide";
+};
+
+export type DepthStackCardLabel =
+ | { readonly contract: "svml.depth-stack-card-label@1"; readonly kind: "none" }
+ | {
+ readonly contract: "svml.depth-stack-card-label@1";
+ readonly kind: "text";
+ readonly document: VisualTextDocument;
+ readonly typography: VisualTextTypography;
+ readonly paints: readonly VisualTextPaintLayer[];
+ readonly flow: VisualTextFlow;
+ };
+
+export type DepthStackCardSpec = {
+ readonly contract: "svml.depth-stack-card-spec@1";
+ readonly id: string;
+ readonly playback: DepthStackCardPlayback;
+};
+
+export type DepthStackCard = {
+ readonly id: string;
+ readonly activationFrame: number;
+ readonly material: MediaLayerSet;
+ readonly label: DepthStackCardLabel;
+ readonly playback: DepthStackCardPlayback;
+};
+
+export type DepthStackCardSet = {
+ readonly contract: "svml.depth-stack-card-set@1";
+ readonly cards: readonly DepthStackCard[];
+};
+
+export type DepthStackHeader = {
+ readonly contract: "svml.depth-stack-header@1";
+ readonly id: string;
+};
+
+export type DepthStackProgram = {
+ readonly contract: "svml.depth-stack-program@1";
+ readonly id: string;
+ readonly span: FrameSpan;
+ readonly terminalFrame: number;
+ readonly frame: SpatialFrame;
+ readonly spec: DepthStackSpec;
+ readonly cards: readonly DepthStackCard[];
+};
+
+export type DepthStackState = ReadonlyMap<number, number>;
diff --git a/packages/deck-track/test/deck-track.test.ts b/packages/deck-track/test/deck-track.test.ts
new file mode 100644
index 00000000..9ded0ca7
--- /dev/null
+++ b/packages/deck-track/test/deck-track.test.ts
@@ -0,0 +1,477 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { videoContractManifests } from "../../test-support/video-domain.js";
+
+import { compositionDependency, compositionTypes } from "@narratage/composition";
+import type { VisualElement, VisualTimedSampling } from "@narratage/composition";
+import { createResolvedClosure } from "@narratage/core";
+import {
+ decodeDepthStackLabelSurface,
+ decodeDepthStackSurface,
+ appendDepthStackCard,
+ createDepthStackCardSet,
+ decodeDepthStackSpec,
+ depthStackManifest,
+ finalizeDepthStack,
+ noDepthStackCardLabel,
+ renderDepthStack,
+ resolveDepthStackPose,
+ resolveDepthStackState,
+ sealDepthStackCardLabel,
+ sealDepthStackCardSpec,
+ sealDepthStackHeader,
+ sealDepthStackSpec,
+} from "@narratage/deck-track";
+import type {
+ DepthStackCardLabel,
+ DepthStackProgram,
+ DepthStackSpec,
+} from "@narratage/deck-track";
+import type { FontArtifactRef } from "@narratage/media";
+import { mediaTypes } from "@narratage/media";
+import type { MediaLayerSet } from "@narratage/media-track";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes, sealProgramSpace } from "@narratage/program-space";
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest } from "@narratage/protocol";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { sealCanvasSpace, sealSpatialFrame, spatialTypes } from "@narratage/spatial";
+import { svsRecipeType } from "@narratage/svs";
+import type { SvsRecipe } from "@narratage/svs";
+import type {
+ StructuredElement,
+ StructuredNode,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+import { artifactTypes } from "@narratage/artifact";
+import { mediaTrackManifest } from "@narratage/media-track";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 2,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const canvas = sealCanvasSpace({
+ contract: "svml.canvas-space@1",
+ widthPx: 360,
+ heightPx: 640,
+ origin: "top-left",
+ xDirection: "right",
+ yDirection: "down",
+ pixelAspect: "square",
+});
+const frame = sealSpatialFrame({
+ contract: "svml.spatial-frame@1",
+ xPx: 60,
+ yPx: 220,
+ widthPx: 240,
+ heightPx: 180,
+});
+
+const image = (name: string) => ({
+ kind: "blob" as const,
+ digest: digestOf(`deck-image:${name}`),
+ size: 16,
+ mediaType: "image/png",
+});
+const video = (name: string) => ({
+ kind: "blob" as const,
+ digest: digestOf(`deck-video:${name}`),
+ size: 32,
+ mediaType: "video/mp4",
+});
+
+function stillMaterial(name: string): MediaLayerSet {
+ return {
+ contract: "svml.media-layer-set@1",
+ layers: [{
+ id: `${name}:sample`,
+ kind: "sample",
+ source: {
+ kind: "still",
+ artifact: image(name),
+ extent: { contract: "svml.intrinsic-extent@1", widthPx: 120, heightPx: 90 },
+ },
+ fit: {
+ contract: "svml.content-fit@1",
+ sizing: "cover",
+ framePoint: { x: 0.5, y: 0.5 },
+ contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 },
+ constraint: "bounded",
+ },
+ appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
+ }],
+ };
+}
+
+function timedMaterial(name: string, occupancy: "loop" | "hold" = "loop"): MediaLayerSet {
+ return {
+ contract: "svml.media-layer-set@1",
+ layers: [{
+ id: `${name}:sample`,
+ kind: "sample",
+ source: {
+ kind: "timed",
+ artifact: video(name),
+ extent: { contract: "svml.intrinsic-extent@1", widthPx: 120, heightPx: 90 },
+ frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 12,
+ },
+ fit: {
+ contract: "svml.content-fit@1",
+ sizing: "contain",
+ framePoint: { x: 0.5, y: 0.5 },
+ contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 },
+ constraint: "bounded",
+ },
+ occupancy: { mode: occupancy, align: "start" },
+ appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
+ }],
+ };
+}
+
+function baseSpec(input: Partial<DepthStackSpec> = {}): DepthStackSpec {
+ return sealDepthStackSpec({
+ contract: "svml.depth-stack-spec@1",
+ visibility: { previous: 2, next: 1, wrap: false },
+ poses: {
+ current: {
+ xPx: 0, yPx: 0, scale: 1, rotationDeg: 0, opacity: 1, stacking: 0,
+ tone: { brightness: 1, contrast: 1, saturation: 1 },
+ },
+ previous: {
+ xPerDepthPx: -8, yPerDepthPx: 18, scalePerDepth: 0.9, rotationPerDepthDeg: -4,
+ rotationMode: "alternate", opacityPerDepth: 0.8, stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.9, contrast: 1, saturation: 0.8 },
+ },
+ next: {
+ xPerDepthPx: 8, yPerDepthPx: -14, scalePerDepth: 0.92, rotationPerDepthDeg: 3,
+ rotationMode: "alternate", opacityPerDepth: 0.7, stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.85, contrast: 1, saturation: 0.75 },
+ },
+ },
+ reflow: { durationFrames: 4, easing: "ease-in-out" },
+ presentation: {
+ clip: { kind: "rounded", radiusPx: 18 },
+ padding: { topPx: 8, rightPx: 8, bottomPx: 8, leftPx: 8 },
+ border: { widthPx: 2, style: "solid", color: "#ffffff" },
+ shadows: [{ offsetX: 0, offsetY: 6, blurPx: 14, spreadPx: 0, color: "#00000088" }],
+ },
+ motion: {
+ enter: { operator: "fade", durationFrames: 2, easing: "linear" },
+ sustain: [{ operator: "float", amount: 2, cycles: 1 }],
+ exit: { operator: "fade", durationFrames: 2, easing: "linear" },
+ },
+ stackingOrder: 30,
+ ...input,
+ });
+}
+
+function cardSpec(id: string, past: "hold-tail" | "continue" | "hide" = "hold-tail", future: "hold-head" | "continue" = "hold-head") {
+ return sealDepthStackCardSpec({
+ contract: "svml.depth-stack-card-spec@1",
+ id,
+ playback: { future, past },
+ });
+}
+
+function program(input: {
+ readonly spec?: DepthStackSpec;
+ readonly materials?: readonly MediaLayerSet[];
+ readonly labels?: readonly DepthStackCardLabel[];
+ readonly playbacks?: readonly ReturnType<typeof cardSpec>[];
+ readonly triggers?: readonly number[];
+ readonly terminal?: number;
+} = {}): DepthStackProgram {
+ const triggers = input.triggers ?? [0, 20, 40];
+ let set = createDepthStackCardSet();
+ for (const [index, trigger] of triggers.entries()) {
+ const id = `card-${index + 1}`;
+ set = appendDepthStackCard(
+ set,
+ input.materials?.[index] ?? stillMaterial(id),
+ input.labels?.[index] ?? noDepthStackCardLabel(),
+ input.playbacks?.[index] ?? cardSpec(id),
+ trigger,
+ );
+ }
+ return finalizeDepthStack(
+ set,
+ sealDepthStackHeader({ contract: "svml.depth-stack-header@1", id: "proof-stack" }),
+ frame,
+ input.spec ?? baseSpec(),
+ input.terminal ?? 60,
+ space,
+ );
+}
+
+function element(track: ReturnType<typeof renderDepthStack>, presentId: string, predicate: (value: VisualElement) => boolean): VisualElement {
+ const value = track.presents.find((present) => present.id === presentId)?.elements.find(predicate);
+ assert(value !== undefined, `${presentId} element is missing`);
+ return value;
+}
+
+test("finite DepthStack state resolves previous-only, next-only, mixed and zero-neighbor boundaries", () => {
+ const value = program({ triggers: [0, 10, 20, 30, 40], terminal: 60 });
+ assert.deepEqual([...resolveDepthStackState(value, 0)], [[0, 0], [1, 1]]);
+ assert.deepEqual([...resolveDepthStackState(value, 2)], [[2, 0], [1, -1], [0, -2], [3, 1]]);
+ assert.deepEqual([...resolveDepthStackState(value, 4)], [[4, 0], [3, -1], [2, -2]]);
+ const zero = program({ spec: baseSpec({ visibility: { previous: 0, next: 0, wrap: false } }) });
+ assert.deepEqual([...resolveDepthStackState(zero, 1)], [[1, 0]]);
+});
+
+test("explicit wrapping never aliases one Card into several relative depths", () => {
+ const wrapped = program({
+ spec: baseSpec({ visibility: { previous: 1, next: 1, wrap: true } }),
+ triggers: [0, 15, 30, 45],
+ });
+ assert.deepEqual([...resolveDepthStackState(wrapped, 0)], [[0, 0], [3, -1], [1, 1]]);
+ assert.throws(() => program({
+ spec: baseSpec({ visibility: { previous: 2, next: 2, wrap: true } }),
+ triggers: [0, 20, 40],
+ }), /several relative depths/u);
+});
+
+test("missing, equal, reversed and terminal-crossing triggers fail in authored order", () => {
+ assert.throws(() => finalizeDepthStack(
+ createDepthStackCardSet(), sealDepthStackHeader({ contract: "svml.depth-stack-header@1", id: "empty" }),
+ frame, baseSpec(), 60, space,
+ ), /at least one Card/u);
+ assert.throws(() => program({ triggers: [0, 20, 20] }), /strictly increasing/u);
+ assert.throws(() => program({ triggers: [0, 30, 20] }), /strictly increasing/u);
+ assert.throws(() => program({ triggers: [0, 20, 60] }), /terminal must be after/u);
+});
+
+test("relative-depth pose resolves offsets, multiplicative tone and alternating rotation", () => {
+ const spec = baseSpec();
+ assert.deepEqual(resolveDepthStackPose(spec, -1), {
+ xPx: -8, yPx: 18, scale: 0.9, rotationDeg: -4, opacity: 0.8, stacking: -1,
+ tone: { brightness: 0.9, contrast: 1, saturation: 0.8 },
+ });
+ assert.deepEqual(resolveDepthStackPose(spec, -2), {
+ xPx: -16, yPx: 36, scale: 0.81, rotationDeg: 4, opacity: 0.64, stacking: -2,
+ tone: { brightness: 0.81, contrast: 1, saturation: 0.64 },
+ });
+});
+
+test("collection reflow moves the complete old/new union while cut replaces it exactly", () => {
+ const animated = renderDepthStack(canvas, space, program());
+ const stageTwo = animated.presents.filter((present) => present.span.startFrame === 20);
+ assert.deepEqual(stageTwo.map((present) => present.id).sort(), [
+ "card-1:stage:2", "card-2:stage:2", "card-3:stage:2",
+ ]);
+ for (const present of stageTwo) {
+ const pose = present.elements.find((value) => value.id === "deck-pose");
+ assert.deepEqual(pose?.animation?.keyframes.map((value) => value.atFrame), [0, 4, 20]);
+ assert.ok(present.elements.some((value) => value.id === "deck-lifecycle"));
+ assert.ok(present.elements.some((value) => value.id === "deck-sustain-1"));
+ }
+ const cut = renderDepthStack(canvas, space, program({
+ spec: baseSpec({ reflow: { durationFrames: 0, easing: "linear" } }),
+ }));
+ assert.equal(cut.presents.filter((present) => present.span.startFrame === 20).length, 3);
+ assert.ok(cut.presents.filter((present) => present.span.startFrame === 20)
+ .every((present) => present.elements.find((value) => value.id === "deck-pose")?.animation === undefined));
+});
+
+test("timed Cards hold future head/current clock/past tail without renderer playback history", () => {
+ const value = program({
+ materials: [stillMaterial("one"), timedMaterial("two"), stillMaterial("three")],
+ });
+ const track = renderDepthStack(canvas, space, value);
+ const future = element(track, "card-2:stage:1", (value) => value.kind === "video");
+ const current = element(track, "card-2:stage:2", (value) => value.kind === "video");
+ const past = element(track, "card-2:stage:3", (value) => value.kind === "video");
+ assert.equal(future.kind, "video");
+ assert.equal(current.kind, "video");
+ assert.equal(past.kind, "video");
+ assert.equal((future.sampling as VisualTimedSampling).segments[0]?.rate.numerator, 0);
+ assert.deepEqual((current.sampling as VisualTimedSampling).segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
+ assert.equal((past.sampling as VisualTimedSampling).segments[0]?.sourceFrame.numerator, 11);
+ assert.equal((past.sampling as VisualTimedSampling).segments[0]?.rate.numerator, 0);
+});
+
+test("continue uses one explicit loop-start clock and past hide removes the retained state", () => {
+ const continued = renderDepthStack(canvas, space, program({
+ materials: [timedMaterial("one"), timedMaterial("two"), stillMaterial("three")],
+ playbacks: [cardSpec("card-1", "continue"), cardSpec("card-2", "hold-tail", "continue"), cardSpec("card-3")],
+ }));
+ const future = element(continued, "card-2:stage:1", (value) => value.kind === "video");
+ const past = element(continued, "card-1:stage:2", (value) => value.kind === "video");
+ assert.equal(future.kind, "video");
+ assert.equal(past.kind, "video");
+ assert(future.sampling !== undefined);
+ assert(past.sampling !== undefined);
+ assert.deepEqual(future.sampling.segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
+ assert.deepEqual(past.sampling.segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
+ assert.throws(() => renderDepthStack(canvas, space, program({
+ materials: [timedMaterial("one", "hold"), stillMaterial("two"), stillMaterial("three")],
+ playbacks: [cardSpec("card-1", "continue"), cardSpec("card-2"), cardSpec("card-3")],
+ })), /continue playback requires loop-start/u);
+ const hidden = program({ playbacks: [cardSpec("card-1", "hide"), cardSpec("card-2"), cardSpec("card-3")] });
+ assert.equal(resolveDepthStackState(hidden, 1).has(0), false);
+});
+
+const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ sources: [{ artifact: { kind: "blob", digest: digestOf("deck-font"), size: 64, mediaType: "font/woff2" } }],
+ weight: 700,
+ style: "normal",
+};
+
+function exactLabel(): DepthStackCardLabel {
+ return sealDepthStackCardLabel({
+ contract: "svml.depth-stack-card-label@1",
+ kind: "text",
+ document: { paragraphs: [{ id: "p", inlines: [{ id: "t", kind: "text", text: "Proof" }] }] },
+ typography: {
+ fonts: [font], sizePx: 24, weight: 700, style: "normal", axes: [], features: [], synthesis: "none",
+ kerning: "normal", trackingPx: 0, wordSpacingPx: 0, lineHeight: 1.2, direction: "auto",
+ writingMode: "horizontal-tb", baselineShiftPx: 0, tabSize: 4, indentationPx: 0,
+ paragraphBeforePx: 0, paragraphAfterPx: 0, transform: "none", variantCaps: "normal",
+ verticalAlign: "baseline", decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }],
+ flow: {
+ form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 8, inlineEnd: 8, blockStart: 8, blockEnd: 8 },
+ inlineAlign: "center", blockAlign: "end", wrap: "word", overflow: "clip",
+ clipToFrame: true, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ });
+}
+
+test("optional labels preserve exact fonts and remain inside the Card-owned pose", () => {
+ const track = renderDepthStack(canvas, space, program({ labels: [exactLabel(), noDepthStackCardLabel(), noDepthStackCardLabel()] }));
+ const label = element(track, "card-1:stage:1", (value) => value.kind === "text-flow");
+ assert.equal(label.kind, "text-flow");
+ assert.equal(label.parent, "deck-material:frame");
+ assert.equal(label.typography.fonts?.[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);
+ const authored = exactLabel();
+ assert.equal(authored.kind, "text");
+ assert.throws(() => sealDepthStackCardLabel({
+ ...authored,
+ typography: { ...authored.typography, fonts: undefined },
+ } as unknown as DepthStackCardLabel), /exact font/u);
+});
+
+test("rendering is a pure absolute-frame result", () => {
+ const value = program({ labels: [exactLabel(), noDepthStackCardLabel(), noDepthStackCardLabel()] });
+ assert.deepEqual(renderDepthStack(canvas, space, value), renderDepthStack(canvas, space, structuredClone(value)));
+});
+
+test("the author Surface keeps every source, trigger, terminal, Frame and optional label as graph inputs", async () => {
+ const range = { source: "deck.svml", start: 0, end: 1 };
+ const ref = (path: string): TextAttributeValue => ({ kind: "reference", path });
+ const node = (name: string, attributes: Record<string, TextAttributeValue>, children: StructuredNode[] = []): StructuredElement => ({ kind: "element", name, attributes, children, range });
+ const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({ path, ref: { kind: "record", id: path }, type });
+ const appearance = (path: string, properties: SvsRecipe["properties"]): SurfaceResolvedReference => ({
+ path, ref: { kind: "record", id: path }, type: svsRecipeType,
+ record: { value: { kind: "inline", value: { contract: "svml.svs-recipe@1", path, properties } } } as never,
+ });
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["map", plain("map", semanticMapTypes.complete)], ["space", plain("space", programSpaceTypes.programSpace)],
+ ["canvas", plain("canvas", spatialTypes.canvas)], ["frame", plain("frame", spatialTypes.frame)],
+ ["first", plain("first", artifactTypes.blob)], ["first-extent", plain("first-extent", spatialTypes.extent)],
+ ["second", plain("second", mediaTypes.synchronized)], ["one", plain("one", narrativeTypes.moment)],
+ ["two", plain("two", narrativeTypes.moment)], ["terminal", plain("terminal", narrativeTypes.selection)],
+ ["deck-style", appearance("deck-style", { "visible-previous": 1, "visible-next": 1, "reflow-frames": 4, fit: "cover", "stack-order": 30 })],
+ ["video-style", appearance("video-style", { fit: "contain", playback: "loop-start", "playback-future": "continue" })],
+ ]);
+ const result = await decodeDepthStackSurface({
+ sourceName: "deck.svml",
+ element: node("deck:DepthStack", {
+ id: "proof", map: ref("map"), space: ref("space"), canvas: ref("canvas"), frame: ref("frame"),
+ appearance: ref("deck-style"), until: ref("terminal"),
+ }, [
+ node("deck:Card", { id: "one", source: ref("first"), extent: ref("first-extent"), at: ref("one") }),
+ node("deck:Card", { id: "two", source: ref("second"), at: ref("two"), appearance: ref("video-style") }),
+ ]),
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ assert.equal(result.components.length, 1);
+ assert.deepEqual(Object.keys(result.components[0]!.outputs).sort(), ["program", "track"]);
+ const fragment = result.fragments[0]!;
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-still-media-layer"));
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-timed-media-layer"));
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-depth-stack-moment-card"));
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "finalize-depth-stack-until-selection-end"));
+ assert.equal(fragment.inputs.filter((input) => input.type.name === narrativeTypes.moment.name).length, 2);
+ assert.ok(fragment.exports.every((output) => output.semanticInputs.includes("frame") && output.semanticInputs.includes("terminal")));
+});
+
+test("Label Surface compiles explicit exact-font text rather than media metadata", async () => {
+ const range = { source: "deck.svml", start: 0, end: 1 };
+ const stack = { contract: "svml.font-stack@1" as const, faces: [font] };
+ const result = await decodeDepthStackLabelSurface({
+ sourceName: "deck.svml",
+ element: {
+ kind: "element", name: "deck:Label", attributes: {
+ id: "proof-label", font: { kind: "reference", path: "font" }, size: "28", color: "#ffeecc",
+ }, children: [{ kind: "text", value: "Evidence", range }], range,
+ },
+ resolveReference: (path) => path === "font" ? {
+ path, ref: { kind: "record", id: path }, type: mediaTypes.fontStack,
+ record: { value: { kind: "inline", value: stack } } as never,
+ } : undefined,
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ const value = result.records[0]?.value;
+ assert.equal(value?.kind, "inline");
+ const label = value?.kind === "inline" ? value.value as unknown as DepthStackCardLabel : undefined;
+ assert.equal(label?.kind, "text");
+ if (label?.kind === "text") assert.equal(label.document.paragraphs[0]?.inlines[0]?.kind, "text");
+});
+
+test("another Deck family can coexist by contributing only the existing VisualTrack waist", () => {
+ const other: ModuleManifest = {
+ format: "svml.module@1" as const,
+ name: "example.carousel",
+ version: "1",
+ dependencies: [compositionDependency],
+ types: [], capabilities: [], surfaces: [], producers: [{
+ name: "render-carousel",
+ inputs: [],
+ outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.carousel/render",
+ digest: digestOf("example.carousel/render@1"),
+ },
+ }],
+ };
+ const closure = createResolvedClosure([
+ ...videoContractManifests,
+ mediaTrackManifest,
+ depthStackManifest,
+ other,
+ ]);
+ assert.ok(closure.modules.some((module) => module.ref.name === "@narratage/deck-track"));
+ assert.ok(closure.modules.some((module) => module.ref.name === "example.carousel"));
+ assert.deepEqual(other.producers[0]?.outputs[0]?.type, compositionTypes.visualTrack);
+});
+
+test("SVS decoding exposes all documented depth, frame, motion and playback axes", () => {
+ const value = decodeDepthStackSpec({
+ contract: "svml.svs-recipe@1",
+ path: "studio.deck.proof",
+ properties: {
+ "visible-previous": 3, "visible-next": 2, wrap: false,
+ "previous-y-step": 24, "previous-scale-step": 0.93, "previous-rotation-mode": "alternate",
+ "next-y-step": -18, "next-opacity-step": 0.7, "reflow-frames": 6, "reflow-easing": "ease-out",
+ clip: "rounded", radius: 16, padding: "8 12", "border-width": 2, "border-color": "#ffffff",
+ enter: "fade", "enter-frames": 3, exit: "fade", "exit-frames": 3, "stack-order": 44,
+ },
+ });
+ assert.deepEqual(value.visibility, { previous: 3, next: 2, wrap: false });
+ assert.equal(value.poses.previous.yPerDepthPx, 24);
+ assert.equal(value.reflow.durationFrames, 6);
+ assert.equal(value.presentation.clip.kind, "rounded");
+ assert.equal(value.motion.enter?.durationFrames, 3);
+ assert.equal(value.stackingOrder, 44);
+});
diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.ts
index 6ed63ff8..f635c649 100644
--- a/packages/film/test/film.test.ts
+++ b/packages/film/test/film.test.ts
@@ -3,6 +3,7 @@ import { registerTypeValidatorFacets } from "@narratage/component-kit";
import { programSpaceTypes, sealProgramSpace } from "@narratage/program-space";
import { compositionTypes, sealAudioTrack, sealVisualTrack } from "@narratage/composition";
import type { Composition, Track } from "@narratage/composition";
+import type { FontArtifactRef } from "@narratage/media";
import { sealCanvasSpace, spatialTypes } from "@narratage/spatial";
import assert from "node:assert/strict";
import test from "node:test";
@@ -52,11 +53,13 @@ import {
renderTextTrack,
renderTextTrackImplementationDigest,
sealTextTrackProgram,
+ stillTextMotion,
textTrackFragment,
textTrackManifest,
textTrackProducers,
textTrackTypes,
} from "@narratage/text-track";
+import type { TextStyle } from "@narratage/text-track";
import { admitRecord, TypeValidatorRegistry } from "@narratage/validation";
const space = sealProgramSpace({
@@ -85,17 +88,48 @@ const filmProgram = sealFilmProgram({
id: "main-film",
clearColor: "#000000",
});
+const titleFont: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ sources: [{ artifact: {
+ kind: "blob", digest: digestOf("film-test-title-font"), size: 1, mediaType: "font/woff2",
+ } }],
+ weight: 800,
+ style: "normal",
+};
+const titleStyle: TextStyle = {
+ contract: "svml.text-style@1",
+ id: "title-style",
+ stackingOrder: 60,
+ typography: {
+ fonts: [titleFont], sizePx: 56, weight: 800, style: "normal",
+ axes: [], features: [], synthesis: "none", kerning: "auto", trackingPx: 0,
+ wordSpacingPx: 0, lineHeight: 1.2, direction: "auto", writingMode: "horizontal-tb",
+ baselineShiftPx: 0, tabSize: 4, indentationPx: 0, paragraphBeforePx: 0,
+ paragraphAfterPx: 0, transform: "none", variantCaps: "normal", verticalAlign: "baseline", decorations: [],
+ cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }],
+ area: {
+ inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "center", blockAlign: "center", wrap: "word", overflow: "visible",
+ clipToFrame: false, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ point: { anchorInline: "center", anchorBlock: "center" },
+ path: { side: "left", orientation: "follow", startMarginPx: 0, endMarginPx: 0, align: "start", reverse: false, overflow: "visible" },
+};
const textProgram = sealTextTrackProgram({
contract: "svml.text-track-program@1",
id: "title-track",
items: [{
id: "title",
- text: "Semantic Video Markup Language",
+ sourceOccurrenceId: "program",
span: { startFrame: 10, endFrameExclusive: 100 },
- z: 60,
tieBreak: "title",
- frame: { contract: "svml.spatial-frame@1", xPx: 86.4, yPx: 192, widthPx: 907.2, heightPx: 384 },
- appearance: { color: "#ffffff", fontSizePx: 56, fontWeight: 800 },
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 86.4, yPx: 192, widthPx: 907.2, heightPx: 384 } },
+ document: { paragraphs: [{ id: "title", inlines: [{ kind: "text", id: "title-text", text: "Semantic Video Markup Language" }] }] },
+ style: titleStyle,
+ motion: stillTextMotion(),
}],
});
const background = sealVisualTrack({
@@ -277,7 +311,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"
const documentRecord = result.state.records.find((record) => record.type.module.name === hyperframesTypes.document.module.name);
assert(documentRecord);
const document = inline(documentRecord) as { readonly html: string };
- assert.match(document.html, /Semantic Video Markup Language/u);
+ assert.match(document.html, /data-svml-text-run="title-text"/u);
assert.match(document.html, /background-track/u);
assert.equal(result.state.records.filter((record) => record.type.name === filmTypes.trackSet.name).length, 4);
});
diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.ts
index 78eb0fc8..b69cf4ec 100644
--- a/packages/hyperframes/src/document.ts
+++ b/packages/hyperframes/src/document.ts
@@ -22,6 +22,11 @@ import type {
HyperframesDocument,
HyperframesFrameSpan,
} from "./types.js";
+import {
+ collectTerminalTextFonts,
+ renderTerminalTextElement,
+ terminalTextLayoutScript,
+} from "./text.js";
export const compileHyperframesImplementationDigest = digestOf("@narratage/hyperframes/compile@1");
@@ -178,6 +183,15 @@ function css(style: readonly VisualStyleDeclaration[]): string {
return style.map(({ name, value }) => `${name}:${String(value)}`).join(";");
}
+function pixelDimension(style: readonly VisualStyleDeclaration[], name: string): number | undefined {
+ const value = style.find((declaration) => declaration.name === name)?.value;
+ if (typeof value !== "string") return undefined;
+ const match = /^(?:0|[1-9][0-9]*(?:\.[0-9]+)?)px$/u.exec(value);
+ if (match === null) return undefined;
+ const parsed = Number.parseFloat(value.slice(0, -2));
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
function attributes(values: readonly VisualAttribute[] | undefined): string {
return (values ?? []).map(({ name, value }) => ` ${name}="${escapeHtml(value)}"`).join("");
}
@@ -209,6 +223,7 @@ function renderElement(
readonly presentId: string;
readonly presentStart: string;
readonly presentDuration: string;
+ readonly presentDurationFrames: number;
readonly presentStartFrame: number;
readonly programNumerator: number;
readonly programDenominator: number;
@@ -219,6 +234,9 @@ function renderElement(
const animationName = element.animation === undefined
? undefined
: stableDomId(["animation", context.trackId, context.presentId, element.id]);
+ const animationProperties = element.animation === undefined
+ ? []
+ : [...new Set(element.animation.keyframes.flatMap((keyframe) => keyframe.style.map((declaration) => declaration.name)))].sort();
const inlineStyle = [
css(element.style),
...exactFontStyle(element),
@@ -234,12 +252,81 @@ function renderElement(
"animation-timing-function:linear",
]),
].filter(Boolean).join(";");
- const common = `id="${id}" data-svml-element-id="${escapeHtml(element.id)}" style="${escapeHtml(inlineStyle)}"${attributes(element.attributes)}`;
+ const commonAttributes = `id="${id}" data-svml-element-id="${escapeHtml(element.id)}"${attributes(element.attributes)}`;
+ const animationAttributes = animationName === undefined
+ ? ""
+ : ` data-svml-frame-animation data-svml-animation-start-frame="${context.presentStartFrame}" data-svml-animation-duration-frames="${context.presentDurationFrames}" data-svml-animation-properties="${animationProperties.join(",")}"`;
+ const common = `${commonAttributes}${animationAttributes} style="${escapeHtml(inlineStyle)}"`;
+ if (element.kind === "mask") {
+ const direct = children.get(element.id) ?? [];
+ const maskRoot = direct.find((child) => child.id === element.maskElement);
+ const contentRoot = direct.find((child) => child.id === element.contentElement);
+ if (maskRoot === undefined || contentRoot === undefined || direct.length !== 2) {
+ throw new Error(`Local mask ${element.id} is missing its declared owned roots.`);
+ }
+ const maskId = stableDomId([context.trackId, context.presentId, element.id, "mask"]);
+ const maskWidth = pixelDimension(element.style, "width");
+ const maskHeight = pixelDimension(element.style, "height");
+ const viewport = maskWidth === undefined || maskHeight === undefined
+ ? ""
+ : ` viewBox="0 0 ${maskWidth} ${maskHeight}" preserveAspectRatio="none"`;
+ const renderOwned = (child: VisualElement) => renderElement(child, children, context);
+ if ((children.get(maskRoot.id) ?? []).length !== 0) {
+ throw new Error(`Local mask ${element.id} mask source must be one terminal owned element.`);
+ }
+ const maskSource = (() => {
+ if (maskRoot.kind === "text") {
+ const alignment = maskRoot.style.find((declaration) => declaration.name === "text-align")?.value;
+ const anchor = alignment === "right" || alignment === "end" ? "end" : alignment === "left" || alignment === "start" ? "start" : "middle";
+ const blockAlignment = maskRoot.style.find((declaration) => declaration.name === "align-items")?.value;
+ const paddingLeft = pixelDimension(maskRoot.style, "padding-left") ?? 0;
+ const paddingRight = pixelDimension(maskRoot.style, "padding-right") ?? 0;
+ const paddingTop = pixelDimension(maskRoot.style, "padding-top") ?? 0;
+ const paddingBottom = pixelDimension(maskRoot.style, "padding-bottom") ?? 0;
+ const x = maskWidth === undefined
+ ? anchor === "start" ? "0" : anchor === "end" ? "100%" : "50%"
+ : String(anchor === "start" ? paddingLeft : anchor === "end" ? maskWidth - paddingRight : (paddingLeft + maskWidth - paddingRight) / 2);
+ const y = maskHeight === undefined
+ ? blockAlignment === "flex-start" ? "0" : blockAlignment === "flex-end" ? "100%" : "50%"
+ : String(blockAlignment === "flex-start" ? paddingTop : blockAlignment === "flex-end" ? maskHeight - paddingBottom : (paddingTop + maskHeight - paddingBottom) / 2);
+ const baseline = blockAlignment === "flex-start" ? "text-before-edge" : blockAlignment === "flex-end" ? "text-after-edge" : "central";
+ const textStyle = [css(maskRoot.style), ...exactFontStyle(maskRoot), "fill:currentColor"].filter(Boolean).join(";");
+ return `<text${attributes(maskRoot.attributes)} x="${x}" y="${y}" text-anchor="${anchor}" dominant-baseline="${baseline}" style="${escapeHtml(textStyle)}">${escapeHtml(maskRoot.text)}</text>`;
+ }
+ if (maskRoot.kind === "text-flow" || maskRoot.kind === "path-text") {
+ return `<foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(maskRoot)}</div></foreignObject>`;
+ }
+ if (maskRoot.kind === "image") {
+ return `<image x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesArtifactUri(maskRoot.artifact.digest))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+ }
+ if (maskRoot.kind === "surface" && maskRoot.surface.timing.kind === "still") {
+ return `<image x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesArtifactUri(maskRoot.surface.artifact.digest))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+ }
+ throw new Error(`Local mask ${element.id} requires a terminal owned text, image or still Surface mask source.`);
+ })();
+ return `<svg ${common}${viewport} width="100%" height="100%" overflow="visible"><defs><mask id="${maskId}" x="0" y="0" width="100%" height="100%" maskUnits="userSpaceOnUse" maskContentUnits="userSpaceOnUse" style="mask-type:${element.mode}">${maskSource}</mask></defs><foreignObject x="0" y="0" width="100%" height="100%" mask="url(#${maskId})"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(contentRoot)}</div></foreignObject></svg>`;
+ }
const descendants = (children.get(element.id) ?? [])
.map((child) => renderElement(child, children, context))
.join("");
if (element.kind === "box") return `<div ${common}>${descendants}</div>`;
if (element.kind === "text") return `<div ${common}>${escapeHtml(element.text)}${descendants}</div>`;
+ if (element.kind === "text-flow" || element.kind === "path-text") {
+ return renderTerminalTextElement(element, {
+ trackId: context.trackId,
+ presentId: context.presentId,
+ durationFrames: context.presentDurationFrames,
+ durationSeconds: context.presentDuration,
+ presentStartFrame: context.presentStartFrame,
+ programNumerator: context.programNumerator,
+ programDenominator: context.programDenominator,
+ escape: escapeHtml,
+ stableId: stableDomId,
+ exactFontFamily,
+ baseStyle: inlineStyle,
+ commonAttributes,
+ });
+ }
if ((element.kind === "video" || element.kind === "surface") && element.sampling !== undefined) {
const artifact = element.kind === "surface" ? element.surface.artifact : element.artifact;
const source = escapeHtml(hyperframesArtifactUri(artifact.digest));
@@ -327,6 +414,7 @@ function renderVisualPresent(
presentId: present.id,
presentStart: start,
presentDuration: duration,
+ presentDurationFrames: present.span.endFrameExclusive - present.span.startFrame,
presentStartFrame: present.span.startFrame,
programNumerator: numerator,
programDenominator: denominator,
@@ -338,6 +426,15 @@ function renderVisualPresent(
function renderAnimationRules(track: VisualTrack, present: VisualPresent): string[] {
const durationFrames = present.span.endFrameExclusive - present.span.startFrame;
return present.elements.flatMap((element) => {
+ if (element.kind === "text-flow" || element.kind === "path-text") {
+ if (element.animation === undefined) return [];
+ const name = stableDomId(["animation", track.id, present.id, element.id]);
+ const frames = element.animation.keyframes.map((keyframe) => {
+ const easing = keyframe.easing === undefined ? "" : `;animation-timing-function:${keyframe.easing}`;
+ return `${percentage(keyframe.atFrame, durationFrames)}{${css(keyframe.style)}${easing}}`;
+ }).join("");
+ return [`@keyframes ${name}{${frames}}`];
+ }
if (element.animation === undefined) return [];
const name = stableDomId(["animation", track.id, present.id, element.id]);
const frames = element.animation.keyframes.map((keyframe) => {
@@ -385,6 +482,11 @@ function collectArtifacts(composition: Composition): BlobRef[] {
for (const source of font.sources) add(source.artifact);
}
}
+ if (element.kind === "text-flow" || element.kind === "path-text") {
+ for (const font of collectTerminalTextFonts(element)) {
+ for (const source of font.sources) add(source.artifact);
+ }
+ }
}
}
}
@@ -402,6 +504,15 @@ function collectFonts(composition: Composition): FontArtifactRef[] {
}
}
}
+ for (const track of composition.tracks) {
+ if (track.contract !== "svml.visual-track@1") continue;
+ for (const present of track.presents) {
+ for (const element of present.elements) {
+ if (element.kind !== "text-flow" && element.kind !== "path-text") continue;
+ for (const font of collectTerminalTextFonts(element)) fonts.set(digestOf(font), font);
+ }
+ }
+ }
return [...fonts.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, font]) => font);
}
@@ -425,6 +536,58 @@ function renderFontFaces(composition: Composition): string {
].join(""))).join("\n ");
}
+function hasTerminalText(composition: Composition): boolean {
+ return composition.tracks.some((track) => track.contract === "svml.visual-track@1"
+ && track.presents.some((present) => present.elements.some((element) =>
+ element.kind === "text-flow" || element.kind === "path-text")));
+}
+
+function hasFrameAnimations(composition: Composition): boolean {
+ return composition.tracks.some((track) => track.contract === "svml.visual-track@1"
+ && track.presents.some((present) => present.elements.some((element) => element.animation !== undefined)));
+}
+
+function frameAnimationRuntime(numerator: number, denominator: number): string {
+ return String.raw`
+(() => {
+ const numerator = ${numerator};
+ const denominator = ${denominator};
+ const millisecondsPerFrame = denominator * 1000 / numerator;
+ const timelines = [];
+ for (const element of document.querySelectorAll("[data-svml-frame-animation]")) {
+ void element.getBoundingClientRect();
+ const animation = element.getAnimations()[0];
+ if (animation === undefined) throw new Error("Visual IR frame animation did not materialize.");
+ const start = Number(element.getAttribute("data-svml-animation-start-frame"));
+ const duration = Number(element.getAttribute("data-svml-animation-duration-frames"));
+ const properties = String(element.getAttribute("data-svml-animation-properties") || "")
+ .split(",").filter(Boolean);
+ const frames = [];
+ for (let frame = 0; frame <= duration; frame += 1) {
+ animation.currentTime = frame * millisecondsPerFrame;
+ animation.pause();
+ const style = getComputedStyle(element);
+ frames.push(properties.map((property) => [property, style.getPropertyValue(property)]));
+ }
+ animation.cancel();
+ element.style.animationName = "none";
+ timelines.push({ element, start, duration, frames });
+ }
+ const applyFrame = (time) => {
+ const programFrame = Math.max(0, Math.round(Number(time || 0) * numerator / denominator));
+ for (const timeline of timelines) {
+ const localFrame = Math.max(0, Math.min(timeline.duration, programFrame - timeline.start));
+ for (const [property, value] of timeline.frames[localFrame]) {
+ timeline.element.style.setProperty(property, value);
+ }
+ }
+ void document.documentElement.getBoundingClientRect();
+ };
+ applyFrame(0);
+ window.addEventListener("hf-seek", (event) => applyFrame(event.detail?.time));
+})();`;
+}
+
function emitHtml(composition: Composition, programSpace: ProgramSpace): string {
const { numerator, denominator } = programSpace.frameRate;
const visuals = orderedVisualPresents(composition.tracks);
@@ -434,6 +597,12 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
const duration = frameSeconds(programSpaceFrameCount(programSpace), numerator, denominator);
const fps = fpsRational(numerator, denominator);
const frameCount = programSpaceFrameCount(programSpace);
+ const textRuntime = hasTerminalText(composition)
+ ? `\n <script>\n ${terminalTextLayoutScript}\n </script>`
+ : "";
+ const animationRuntime = hasFrameAnimations(composition)
+ ? `\n <script>\n ${frameAnimationRuntime(numerator, denominator)}\n </script>`
+ : "";
return `<!doctype html>
<html>
<head>
@@ -450,18 +619,7 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
<body>
<div data-composition-id="${escapeHtml(composition.id)}" data-start="0" data-no-timeline data-width="${composition.canvas.width}" data-height="${composition.canvas.height}" data-duration="${duration}" data-fps="${fps}" data-svml-frame-count="${frameCount}">
${visualHtml}
- </div>
- <script>
- window.addEventListener("hf-seek", (event) => {
- // HyperFrames 0.7.101 exposes a per-seek readiness barrier. One browser
- // task gives Chromium's compositor the same commit opportunity even
- // when this worker begins at a non-zero frame, so partition boundaries
- // cannot leak first-paint state into captured pixels.
- if (event && event.detail && typeof event.detail.waitUntil === "function") {
- event.detail.waitUntil(new Promise((resolve) => setTimeout(resolve, 16)));
- }
- });
- </script>
+ </div>${animationRuntime}${textRuntime}
</body>
</html>
`;
diff --git a/packages/hyperframes/src/text.ts b/packages/hyperframes/src/text.ts
new file mode 100644
index 00000000..d3c3a8f5
--- /dev/null
+++ b/packages/hyperframes/src/text.ts
@@ -0,0 +1,1070 @@
+import type { FontArtifactRef } from "@narratage/media";
+import type {
+ VisualColorPaint,
+ VisualPathTextElement,
+ VisualTextDocument,
+ VisualTextFlowElement,
+ VisualTextPaintLayer,
+ VisualTextRunStyle,
+ VisualTextSequenceAnimation,
+ VisualTextTypography,
+ VisualVectorPathCommand,
+} from "@narratage/composition";
+import { digestOf } from "@narratage/protocol";
+
+type TerminalTextElement = VisualTextFlowElement | VisualPathTextElement;
+
+export type TextRenderContext = {
+ readonly trackId: string;
+ readonly presentId: string;
+ readonly durationFrames: number;
+ readonly durationSeconds: string;
+ readonly presentStartFrame: number;
+ readonly programNumerator: number;
+ readonly programDenominator: number;
+ readonly escape: (value: string) => string;
+ readonly stableId: (parts: readonly string[]) => string;
+ readonly exactFontFamily: (font: FontArtifactRef) => string;
+ readonly baseStyle: string;
+ readonly commonAttributes: string;
+};
+
+function number(value: number): string {
+ if (Object.is(value, -0)) return "0";
+ return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(8)));
+}
+
+function colorStop(stop: { readonly offset: number; readonly color: string; readonly opacity: number }): string {
+ const color = stop.opacity === 1
+ ? stop.color
+ : `color-mix(in srgb,${stop.color} ${number(stop.opacity * 100)}%,transparent)`;
+ return `${color} ${number(stop.offset * 100)}%`;
+}
+
+export function colorPaintCss(paint: VisualColorPaint): string {
+ if (paint.kind === "solid") return paint.color;
+ const stops = paint.stops.map(colorStop).join(",");
+ if (paint.kind === "linear-gradient") return `linear-gradient(${number(paint.angleDeg)}deg,${stops})`;
+ return `radial-gradient(circle at ${number(paint.center.x * 100)}% ${number(paint.center.y * 100)}%,${stops})`;
+}
+
+function solidPaint(paint: VisualColorPaint): string | undefined {
+ return paint.kind === "solid" ? paint.color : undefined;
+}
+
+function exactFontCss(fonts: readonly FontArtifactRef[] | undefined, exactFontFamily: TextRenderContext["exactFontFamily"]): string[] {
+ if (fonts === undefined) return [];
+ return [
+ `font-family:${fonts.map(exactFontFamily).join(",")}`,
+ `font-weight:${fonts[0]!.weight}`,
+ `font-style:${fonts[0]!.style}`,
+ "font-synthesis:none",
+ ];
+}
+
+function typographyCss(
+ typography: VisualTextTypography,
+ exactFontFamily: TextRenderContext["exactFontFamily"],
+): string[] {
+ const synthesis = typography.synthesis === "weight-style"
+ ? "weight style"
+ : typography.synthesis;
+ const decorations = typography.decorations;
+ const decoration = decorations[0];
+ if (decorations.some((item) => item.paint.kind !== "solid")) {
+ throw new Error("HyperFrames Text decorations currently require solid Paint.");
+ }
+ if (decoration !== undefined && decorations.some((item) =>
+ item.style !== decoration.style
+ || item.paint.kind !== "solid"
+ || decoration.paint.kind !== "solid"
+ || item.paint.color !== decoration.paint.color
+ || item.thicknessPx !== decoration.thicknessPx
+ || item.offsetPx !== decoration.offsetPx
+ || item.skipInk !== decoration.skipInk)) {
+ throw new Error("HyperFrames Text decorations on one run must share Paint and metric settings.");
+ }
+ return [
+ ...(typography.fonts === undefined
+ ? [`font-family:${typography.prototypeFamily}`]
+ : exactFontCss(typography.fonts, exactFontFamily)),
+ `font-size:${number(typography.sizePx)}px`,
+ `font-weight:${typography.weight}`,
+ `font-style:${typography.style}`,
+ `font-synthesis:${synthesis}`,
+ `font-kerning:${typography.kerning}`,
+ `font-variation-settings:${typography.axes.length === 0 ? "normal" : typography.axes.map((axis) => `"${axis.tag}" ${number(axis.value)}`).join(",")}`,
+ `font-feature-settings:${typography.features.length === 0 ? "normal" : typography.features.map((feature) => `"${feature.tag}" ${feature.enabled ? 1 : 0}`).join(",")}`,
+ `letter-spacing:${number(typography.trackingPx)}px`,
+ `word-spacing:${number(typography.wordSpacingPx)}px`,
+ `line-height:${number(typography.lineHeight)}`,
+ ...(typography.direction === "auto" ? [] : [`direction:${typography.direction}`]),
+ `writing-mode:${typography.writingMode}`,
+ `text-transform:${typography.transform}`,
+ `font-variant-caps:${typography.variantCaps}`,
+ `tab-size:${typography.tabSize}`,
+ `text-indent:${number(typography.indentationPx)}px`,
+ ...(typography.baselineShiftPx === 0 ? [] : [`vertical-align:${number(typography.baselineShiftPx)}px`]),
+ ...(typography.baselineShiftPx !== 0 || typography.verticalAlign === "baseline" ? [] : [`vertical-align:${typography.verticalAlign}`]),
+ `text-autospace:${typography.cjk.textSpacing === "normal" ? "normal" : "no-autospace"}`,
+ `text-spacing-trim:${typography.cjk.punctuationTrim === "none" ? "space-all" : typography.cjk.punctuationTrim === "start" ? "trim-start" : typography.cjk.punctuationTrim === "adjacent" ? "trim-both" : typography.cjk.punctuationTrim === "all" ? "trim-all" : "space-first"}`,
+ ...(decoration === undefined ? [] : [
+ `text-decoration-line:${decorations.map((item) => item.line).join(" ")}`,
+ `text-decoration-color:${decoration.paint.kind === "solid" ? decoration.paint.color : "currentColor"}`,
+ `text-decoration-style:${decoration.style}`,
+ ...(decoration.thicknessPx === undefined ? [] : [`text-decoration-thickness:${number(decoration.thicknessPx)}px`]),
+ ...(decoration.offsetPx === undefined ? [] : [`text-underline-offset:${number(decoration.offsetPx)}px`]),
+ `text-decoration-skip-ink:${decoration.skipInk ? "auto" : "none"}`,
+ ]),
+ ];
+}
+
+function textLanguageAttributes(
+ typography: VisualTextTypography,
+ escape: TextRenderContext["escape"],
+ language?: string,
+ direction?: "auto" | "ltr" | "rtl",
+): string {
+ const actualLanguage = language ?? typography.language;
+ const actualDirection = direction ?? typography.direction;
+ return [
+ ...(actualLanguage === undefined ? [] : [`lang="${escape(actualLanguage)}"`]),
+ `dir="${actualDirection}"`,
+ ].join(" ");
+}
+
+function mergedTypography(
+ base: VisualTextTypography,
+ style: VisualTextRunStyle | undefined,
+): VisualTextTypography {
+ const override = style?.typography;
+ if (override === undefined) return base;
+ const fontSelection = override.fonts !== undefined
+ ? { fonts: override.fonts }
+ : override.prototypeFamily !== undefined
+ ? { prototypeFamily: override.prototypeFamily }
+ : base.fonts === undefined
+ ? { prototypeFamily: base.prototypeFamily! }
+ : { fonts: base.fonts };
+ const {
+ fonts: _fonts,
+ prototypeFamily: _prototypeFamily,
+ axes: _axes,
+ features: _features,
+ decorations: _decorations,
+ cjk: _cjk,
+ ...scalarOverrides
+ } = override;
+ return {
+ ...base,
+ ...scalarOverrides,
+ ...fontSelection,
+ axes: override.axes ?? base.axes,
+ features: override.features ?? base.features,
+ decorations: override.decorations ?? base.decorations,
+ cjk: override.cjk === undefined ? base.cjk : { ...base.cjk, ...override.cjk },
+ };
+}
+
+type GlyphPaintLayer = Exclude<VisualTextPaintLayer, { readonly kind: "box" }>;
+
+function glyphPaintLayers(paints: readonly VisualTextPaintLayer[]): GlyphPaintLayer[] {
+ return paints.filter((paint): paint is GlyphPaintLayer => paint.kind !== "box");
+}
+
+function inheritedGlyphColor(paints: readonly VisualTextPaintLayer[]): string[] {
+ const fills = glyphPaintLayers(paints).filter((paint): paint is Extract<GlyphPaintLayer, { kind: "fill" }> => paint.kind === "fill");
+ return fills.length === 1 && fills[0]!.paint.kind === "solid" ? [`color:${fills[0]!.paint.color}`] : [];
+}
+
+function glyphFilterId(
+ paint: Extract<GlyphPaintLayer, { kind: "stroke" | "shadow" | "glow" }>,
+ context: TextRenderContext,
+): string {
+ return context.stableId([context.trackId, context.presentId, "text-glyph-filter", digestOf(paint)]);
+}
+
+function glyphFilterDefinition(
+ paint: Extract<GlyphPaintLayer, { kind: "stroke" | "shadow" | "glow" }>,
+ context: TextRenderContext,
+): string {
+ const color = solidPaint(paint.paint);
+ if (color === undefined) {
+ throw new Error(`HyperFrames ${paint.kind} Text Paint requires solid color; materialize gradient ${paint.kind} as a Surface.`);
+ }
+ const id = glyphFilterId(paint, context);
+ const flood = `<feFlood flood-color="${context.escape(color)}" result="paint"/>`;
+ if (paint.kind === "stroke") {
+ const radius = paint.placement === "center" ? paint.widthPx / 2 : paint.widthPx;
+ const expanded = `<feMorphology in="SourceAlpha" operator="dilate" radius="${number(radius)}" result="expanded"/>`;
+ const contracted = `<feMorphology in="SourceAlpha" operator="erode" radius="${number(radius)}" result="contracted"/>`;
+ const ring = paint.placement === "outside"
+ ? `<feComposite in="expanded" in2="SourceAlpha" operator="out" result="shape"/>`
+ : paint.placement === "inside"
+ ? `<feComposite in="SourceAlpha" in2="contracted" operator="out" result="shape"/>`
+ : `<feComposite in="expanded" in2="contracted" operator="out" result="shape"/>`;
+ return `<filter id="${id}" x="-100%" y="-100%" width="300%" height="300%" color-interpolation-filters="sRGB">${expanded}${contracted}${ring}${flood}<feComposite in="paint" in2="shape" operator="in"/></filter>`;
+ }
+ const spread = paint.spreadPx <= 0
+ ? `<feComposite in="SourceAlpha" in2="SourceAlpha" operator="in" result="spread"/>`
+ : `<feMorphology in="SourceAlpha" operator="dilate" radius="${number(paint.spreadPx)}" result="spread"/>`;
+ const blur = `<feGaussianBlur in="spread" stdDeviation="${number(paint.blurPx)}" result="blurred"/>`;
+ const offset = paint.kind === "shadow"
+ ? `<feOffset in="blurred" dx="${number(paint.offsetX)}" dy="${number(paint.offsetY)}" result="shape"/>`
+ : `<feComposite in="blurred" in2="blurred" operator="in" result="shape"/>`;
+ return `<filter id="${id}" x="-100%" y="-100%" width="300%" height="300%" color-interpolation-filters="sRGB">${spread}${blur}${offset}${flood}<feComposite in="paint" in2="shape" operator="in"/></filter>`;
+}
+
+function glyphFilterDefinitions(element: TerminalTextElement, context: TextRenderContext): string {
+ const layers: GlyphPaintLayer[] = [];
+ const append = (paints: readonly VisualTextPaintLayer[] | undefined): void => {
+ layers.push(...glyphPaintLayers(paints ?? []));
+ };
+ append(element.paints);
+ for (const paragraph of element.document.paragraphs) {
+ append(paragraph.style?.paints);
+ for (const inline of paragraph.inlines) if (inline.kind === "text") append(inline.style?.paints);
+ }
+ const filtered = layers.filter((paint): paint is Extract<GlyphPaintLayer, { kind: "stroke" | "shadow" | "glow" }> => paint.kind !== "fill");
+ const definitions = [...new Map(filtered.map((paint) => [digestOf(paint), paint])).values()]
+ .map((paint) => glyphFilterDefinition(paint, context)).join("");
+ return definitions;
+}
+
+function glyphPaintDefinitions(element: TerminalTextElement, context: TextRenderContext): string {
+ const definitions = glyphFilterDefinitions(element, context);
+ return definitions.length === 0 ? "" : `<svg aria-hidden="true" width="0" height="0" style="position:absolute;overflow:hidden"><defs>${definitions}</defs></svg>`;
+}
+
+function glyphLayerCss(
+ paint: GlyphPaintLayer,
+ inheritSolidFill: boolean,
+ context: TextRenderContext,
+): string[] {
+ const common = ["grid-area:1/1", "position:relative", "pointer-events:none"];
+ if (paint.kind === "fill") {
+ if (paint.paint.kind === "solid") return [...common, `color:${inheritSolidFill ? "inherit" : paint.paint.color}`];
+ return [
+ ...common,
+ `background-image:${colorPaintCss(paint.paint)}`,
+ "background-clip:text",
+ "-webkit-background-clip:text",
+ "color:transparent",
+ "-webkit-text-fill-color:transparent",
+ ];
+ }
+ return [
+ ...common,
+ "color:#ffffff",
+ "-webkit-text-fill-color:#ffffff",
+ `filter:url(#${glyphFilterId(paint, context)})`,
+ ];
+}
+
+function renderGlyphPaint(
+ value: string,
+ paints: readonly VisualTextPaintLayer[],
+ context: TextRenderContext,
+): string {
+ const layers = glyphPaintLayers(paints);
+ if (layers.length === 0) return context.escape(value);
+ const singleSolidFill = layers.length === 1 && layers[0]?.kind === "fill" && layers[0].paint.kind === "solid";
+ return layers.map((paint, index) => `<span aria-hidden="${index === layers.length - 1 ? "false" : "true"}" data-svml-text-paint-layer="${index}"${styleAttribute(glyphLayerCss(paint, singleSolidFill, context), context.escape)}>${context.escape(value)}</span>`).join("");
+}
+
+function boxLayers(
+ paints: readonly VisualTextPaintLayer[],
+ target: Extract<VisualTextPaintLayer, { kind: "box" }>["target"],
+ continuity?: "isolated" | "joined",
+): Array<Extract<VisualTextPaintLayer, { kind: "box" }>> {
+ return paints.filter((paint): paint is Extract<VisualTextPaintLayer, { kind: "box" }> =>
+ paint.kind === "box" && paint.target === target && (continuity === undefined || paint.continuity === continuity));
+}
+
+function boxCss(
+ paints: readonly VisualTextPaintLayer[],
+ target: Extract<VisualTextPaintLayer, { kind: "box" }>["target"],
+ continuity?: "isolated" | "joined",
+): string[] {
+ const layers = boxLayers(paints, target, continuity);
+ if (layers.length === 0) return [];
+ const result: string[] = [];
+ const shadows: string[] = [];
+ const backgrounds: string[] = [];
+ for (const layer of layers) {
+ const decoration = layer.decoration;
+ if (decoration.fill !== undefined) {
+ backgrounds.push(decoration.fill.kind === "solid"
+ ? `linear-gradient(${decoration.fill.color},${decoration.fill.color})`
+ : colorPaintCss(decoration.fill));
+ }
+ if (decoration.border !== undefined) {
+ const color = solidPaint(decoration.border.paint);
+ if (color === undefined) throw new Error("HyperFrames Text Box borders require solid Paint.");
+ result.push(
+ `border-style:${decoration.border.style}`,
+ `border-color:${color}`,
+ `border-width:${number(decoration.border.widthsPx.top)}px ${number(decoration.border.widthsPx.right)}px ${number(decoration.border.widthsPx.bottom)}px ${number(decoration.border.widthsPx.left)}px`,
+ );
+ }
+ result.push(
+ `padding:${number(decoration.paddingPx.top)}px ${number(decoration.paddingPx.right)}px ${number(decoration.paddingPx.bottom)}px ${number(decoration.paddingPx.left)}px`,
+ `border-radius:${number(decoration.radiiPx.topLeft)}px ${number(decoration.radiiPx.topRight)}px ${number(decoration.radiiPx.bottomRight)}px ${number(decoration.radiiPx.bottomLeft)}px`,
+ );
+ for (const shadow of decoration.shadows) {
+ const color = solidPaint(shadow.paint);
+ if (color === undefined) throw new Error("HyperFrames Text Box shadows require solid Paint.");
+ shadows.push(`${number(shadow.offsetX)}px ${number(shadow.offsetY)}px ${number(shadow.blurPx)}px ${number(shadow.spreadPx)}px ${color}`);
+ }
+ }
+ if (backgrounds.length > 0) result.push(`background-image:${backgrounds.reverse().join(",")}`);
+ if (shadows.length > 0) result.push(`box-shadow:${shadows.join(",")}`);
+ return result;
+}
+
+function tailHtml(
+ paints: readonly VisualTextPaintLayer[],
+ target: Extract<VisualTextPaintLayer, { kind: "box" }>["target"],
+ context: TextRenderContext,
+ continuity?: "isolated" | "joined",
+): string {
+ return boxLayers(paints, target, continuity).flatMap((layer, index) => {
+ const tail = layer.decoration.tail;
+ if (tail === undefined) return [];
+ const side = tail.side;
+ const position = side === "top"
+ ? `left:${number(tail.offset)}px;top:${number(-tail.heightPx)}px`
+ : side === "bottom"
+ ? `left:${number(tail.offset)}px;bottom:${number(-tail.heightPx)}px`
+ : side === "left"
+ ? `left:${number(-tail.widthPx)}px;top:${number(tail.offset)}px`
+ : `right:${number(-tail.widthPx)}px;top:${number(tail.offset)}px`;
+ const polygon = side === "top" ? "0 100%,50% 0,100% 100%"
+ : side === "bottom" ? "0 0,100% 0,50% 100%"
+ : side === "left" ? "100% 0,0 50%,100% 100%" : "0 0,100% 50%,0 100%";
+ const style = `position:absolute;pointer-events:none;width:${number(tail.widthPx)}px;height:${number(tail.heightPx)}px;${position};background:${colorPaintCss(tail.paint)};clip-path:polygon(${polygon});z-index:${index}`;
+ return [`<span aria-hidden="true" data-svml-text-tail="${side}" style="${context.escape(style)}"></span>`];
+ }).join("");
+}
+
+function flowCss(element: VisualTextFlowElement): string[] {
+ const flow = element.flow;
+ const overflow = flow.overflow === "visible" ? "visible" : "hidden";
+ const align = flow.inlineAlign === "start" ? "start" : flow.inlineAlign === "end" ? "end" : flow.inlineAlign;
+ return [
+ "box-sizing:border-box",
+ `padding:${number(flow.paddingPx.blockStart)}px ${number(flow.paddingPx.inlineEnd)}px ${number(flow.paddingPx.blockEnd)}px ${number(flow.paddingPx.inlineStart)}px`,
+ `text-align:${align}`,
+ `overflow:${overflow}`,
+ `white-space:${flow.wrap === "none" ? "pre" : "pre-wrap"}`,
+ `overflow-wrap:${flow.wrap === "grapheme" ? "anywhere" : flow.wrap === "word" ? "break-word" : "normal"}`,
+ `word-break:${flow.wrap === "grapheme" ? "break-all" : "normal"}`,
+ `column-count:${flow.columns}`,
+ `column-gap:${number(flow.columnGapPx)}px`,
+ ...(flow.inlineSize === "hug" ? ["width:max-content"] : ["width:100%"]),
+ ...(flow.blockSize === "hug" ? ["height:max-content"] : ["height:100%"]),
+ ...(flow.overflow !== "ellipsis" || flow.wrap === "none" ? [] : [
+ "display:-webkit-box",
+ "-webkit-box-orient:vertical",
+ ...(flow.maxLines === undefined ? [] : [`-webkit-line-clamp:${flow.maxLines}`]),
+ ]),
+ ...(flow.overflow === "ellipsis" && flow.wrap === "none" ? ["text-overflow:ellipsis"] : []),
+ ...(flow.metricEdge === "line-box" ? [] : [
+ "text-box-trim:trim-both",
+ `text-box-edge:${flow.metricEdge === "cap-height" ? "cap alphabetic" : "text alphabetic"}`,
+ ]),
+ ];
+}
+
+type UnitIndices = {
+ paragraph: number;
+ run: number;
+ word: number;
+ grapheme: number;
+};
+
+function unitAnimationCss(
+ _element: TerminalTextElement,
+ _unit: VisualTextSequenceAnimation["unit"],
+ _index: number,
+ _context: TextRenderContext,
+): string[] {
+ // Unit-local animation is installed once as typed WAAPI keyframes after
+ // exact-font layout. HyperFrames owns the frame clock and seeks those
+ // persistent animations; no renderer script samples wall time.
+ return [];
+}
+
+function styleAttribute(values: readonly string[], escape: TextRenderContext["escape"]): string {
+ return values.length === 0 ? "" : ` style="${escape(values.join(";"))}"`;
+}
+
+function segmentRun(text: string, language: string | undefined): Array<{ text: string; wordLike: boolean }> {
+ const segmenter = new Intl.Segmenter(language, { granularity: "word" });
+ return [...segmenter.segment(text)].map((segment) => ({ text: segment.segment, wordLike: segment.isWordLike ?? false }));
+}
+
+function graphemes(text: string, language: string | undefined): string[] {
+ return [...new Intl.Segmenter(language, { granularity: "grapheme" }).segment(text)].map((segment) => segment.segment);
+}
+
+function textUnitCounts(document: VisualTextDocument, typography: VisualTextTypography): Record<"paragraph" | "run" | "word" | "grapheme", number> {
+ const result = { paragraph: document.paragraphs.length, run: 0, word: 0, grapheme: 0 };
+ for (const paragraph of document.paragraphs) {
+ const paragraphTypography = mergedTypography(typography, paragraph.style);
+ for (const inline of paragraph.inlines) {
+ if (inline.kind === "break") continue;
+ result.run += 1;
+ const runTypography = mergedTypography(paragraphTypography, inline.style);
+ const language = inline.language ?? runTypography.language;
+ for (const segment of segmentRun(inline.text, language)) {
+ if (segment.wordLike) result.word += 1;
+ result.grapheme += graphemes(segment.text, language).length;
+ }
+ }
+ }
+ return result;
+}
+
+function assertTextUnitRanges(element: TerminalTextElement): void {
+ const counts = textUnitCounts(element.document, element.typography);
+ for (const sequence of element.sequences) {
+ if (sequence.unit !== "line" && sequence.range.endExclusive > counts[sequence.unit]) {
+ throw new Error(`Text sequence ${sequence.id} selects ${sequence.unit} ${sequence.range.endExclusive}, but only ${counts[sequence.unit]} exist.`);
+ }
+ }
+}
+
+function renderDocument(
+ document: VisualTextDocument,
+ element: TerminalTextElement,
+ context: TextRenderContext,
+): string {
+ const indices: UnitIndices = { paragraph: 0, run: 0, word: 0, grapheme: 0 };
+ const renderGrapheme = (value: string, paints: readonly VisualTextPaintLayer[]): string => {
+ const graphemeIndex = indices.grapheme++;
+ const styles = [
+ "position:relative",
+ "display:inline-grid",
+ ...boxCss(paints, "grapheme", "isolated"),
+ ...unitAnimationCss(element, "grapheme", graphemeIndex, context),
+ ];
+ return `<span data-svml-text-unit-grapheme="${graphemeIndex}"${styleAttribute(styles, context.escape)}>${tailHtml(paints, "grapheme", context, "isolated")}${renderGlyphPaint(value, paints, context)}</span>`;
+ };
+ return document.paragraphs.map((paragraph) => {
+ const paragraphIndex = indices.paragraph++;
+ const paragraphTypography = mergedTypography(element.typography, paragraph.style);
+ const paragraphPaints = paragraph.style?.paints ?? element.paints;
+ const content = paragraph.inlines.map((inline) => {
+ if (inline.kind === "break") return "<br/>";
+ const runIndex = indices.run++;
+ const typography = mergedTypography(paragraphTypography, inline.style);
+ const paints = inline.style?.paints ?? paragraphPaints;
+ const runContents = segmentRun(inline.text, inline.language ?? typography.language).map((segment) => {
+ if (!segment.wordLike) {
+ return graphemes(segment.text, inline.language ?? typography.language).map((grapheme) => renderGrapheme(grapheme, paints)).join("");
+ }
+ const wordIndex = indices.word++;
+ const wordContent = graphemes(segment.text, inline.language ?? typography.language).map((grapheme) => renderGrapheme(grapheme, paints)).join("");
+ return `<span data-svml-text-unit-word="${wordIndex}"${styleAttribute([
+ "position:relative",
+ ...boxCss(paints, "word", "isolated"),
+ ...unitAnimationCss(element, "word", wordIndex, context),
+ ], context.escape)}>${tailHtml(paints, "word", context, "isolated")}${wordContent}</span>`;
+ }).join("");
+ const runStyle = [
+ "position:relative",
+ "box-decoration-break:clone",
+ "-webkit-box-decoration-break:clone",
+ ...typographyCss(typography, context.exactFontFamily),
+ ...inheritedGlyphColor(paints),
+ ...boxCss(paints, "run"),
+ ...boxCss(paints, "word", "joined"),
+ ...boxCss(paints, "grapheme", "joined"),
+ ...unitAnimationCss(element, "run", runIndex, context),
+ ];
+ return `<span data-svml-text-run="${context.escape(inline.id)}" data-svml-text-unit-run="${runIndex}" ${textLanguageAttributes(typography, context.escape, inline.language, inline.direction)}${styleAttribute(runStyle, context.escape)}>${tailHtml(paints, "run", context)}${tailHtml(paints, "word", context, "joined")}${tailHtml(paints, "grapheme", context, "joined")}${runContents}</span>`;
+ }).join("");
+ const paragraphStyle = [
+ "position:relative",
+ `margin:${number(paragraphTypography.paragraphBeforePx)}px 0 ${number(paragraphTypography.paragraphAfterPx)}px 0`,
+ ...boxCss(paragraphPaints, "paragraph"),
+ ...unitAnimationCss(element, "paragraph", paragraphIndex, context),
+ ];
+ return `<div data-svml-text-paragraph="${context.escape(paragraph.id)}" data-svml-text-unit-paragraph="${paragraphIndex}" ${textLanguageAttributes(paragraphTypography, context.escape)}${styleAttribute(paragraphStyle, context.escape)}>${tailHtml(paragraphPaints, "paragraph", context)}<span data-svml-text-line-fragments${styleAttribute([
+ "position:relative",
+ "box-decoration-break:clone",
+ "-webkit-box-decoration-break:clone",
+ ...boxCss(paragraphPaints, "line"),
+ ], context.escape)}>${tailHtml(paragraphPaints, "line", context)}${content}</span></div>`;
+ }).join("");
+}
+
+function pathData(commands: readonly VisualVectorPathCommand[]): string {
+ return commands.map((command) => {
+ if (command.kind === "move") return `M ${number(command.x)} ${number(command.y)}`;
+ if (command.kind === "line") return `L ${number(command.x)} ${number(command.y)}`;
+ if (command.kind === "quadratic") return `Q ${number(command.controlX)} ${number(command.controlY)} ${number(command.x)} ${number(command.y)}`;
+ if (command.kind === "cubic") return `C ${number(command.control1X)} ${number(command.control1Y)} ${number(command.control2X)} ${number(command.control2Y)} ${number(command.x)} ${number(command.y)}`;
+ return "Z";
+ }).join(" ");
+}
+
+type PathSegment = (
+ | { readonly kind: "line"; readonly x: number; readonly y: number }
+ | { readonly kind: "quadratic"; readonly controlX: number; readonly controlY: number; readonly x: number; readonly y: number }
+ | { readonly kind: "cubic"; readonly control1X: number; readonly control1Y: number; readonly control2X: number; readonly control2Y: number; readonly x: number; readonly y: number }
+) & { readonly from: { readonly x: number; readonly y: number } };
+
+function reversePath(commands: readonly VisualVectorPathCommand[]): VisualVectorPathCommand[] {
+ const result: VisualVectorPathCommand[] = [];
+ let start: { x: number; y: number } | undefined;
+ let current: { x: number; y: number } | undefined;
+ let segments: PathSegment[] = [];
+ let closed = false;
+ const flush = (): void => {
+ if (start === undefined || current === undefined) return;
+ const reversed = [...segments].reverse();
+ result.push({ kind: "move", x: current.x, y: current.y });
+ for (const segment of reversed) {
+ if (segment.kind === "line") result.push({ kind: "line", x: segment.from.x, y: segment.from.y });
+ else if (segment.kind === "quadratic") result.push({ kind: "quadratic", controlX: segment.controlX, controlY: segment.controlY, x: segment.from.x, y: segment.from.y });
+ else result.push({
+ kind: "cubic", control1X: segment.control2X, control1Y: segment.control2Y,
+ control2X: segment.control1X, control2Y: segment.control1Y, x: segment.from.x, y: segment.from.y,
+ });
+ }
+ if (closed) result.push({ kind: "close" });
+ start = undefined; current = undefined; segments = []; closed = false;
+ };
+ for (const command of commands) {
+ if (command.kind === "move") {
+ flush();
+ start = { x: command.x, y: command.y };
+ current = start;
+ } else if (command.kind === "close") {
+ if (start === undefined || current === undefined) throw new Error("Path close has no open subpath.");
+ if (current.x !== start.x || current.y !== start.y) segments.push({ kind: "line", from: current, x: start.x, y: start.y });
+ current = start;
+ closed = true;
+ } else {
+ if (current === undefined) throw new Error("Path segment has no current point.");
+ if (command.kind === "line") segments.push({ kind: "line", x: command.x, y: command.y, from: current });
+ else if (command.kind === "quadratic") segments.push({ ...command, from: current });
+ else if (command.kind === "cubic") segments.push({ ...command, from: current });
+ else throw new Error("Path segment is unsupported.");
+ current = { x: command.x, y: command.y };
+ }
+ }
+ flush();
+ return result;
+}
+
+function allDocumentPaints(element: TerminalTextElement): VisualColorPaint[] {
+ const result: VisualColorPaint[] = [];
+ const append = (paints: readonly VisualTextPaintLayer[] | undefined): void => {
+ for (const layer of paints ?? []) {
+ if (layer.kind === "box") {
+ if (layer.decoration.fill !== undefined) result.push(layer.decoration.fill);
+ if (layer.decoration.border !== undefined) result.push(layer.decoration.border.paint);
+ } else result.push(layer.paint);
+ }
+ };
+ append(element.paints);
+ for (const paragraph of element.document.paragraphs) {
+ append(paragraph.style?.paints);
+ for (const inline of paragraph.inlines) if (inline.kind === "text") append(inline.style?.paints);
+ }
+ return [...new Map(result.map((paint) => [digestOf(paint), paint])).values()];
+}
+
+function svgPaintId(paint: VisualColorPaint, context: TextRenderContext): string {
+ return context.stableId([context.trackId, context.presentId, "text-paint", digestOf(paint)]);
+}
+
+function svgPaintValue(paint: VisualColorPaint, context: TextRenderContext): string {
+ return paint.kind === "solid" ? paint.color : `url(#${svgPaintId(paint, context)})`;
+}
+
+function svgPaintDefinitions(element: TerminalTextElement, context: TextRenderContext): string {
+ return allDocumentPaints(element).flatMap((paint) => {
+ if (paint.kind === "solid") return [];
+ const stops = paint.stops.map((stop) => `<stop offset="${number(stop.offset * 100)}%" stop-color="${context.escape(stop.color)}" stop-opacity="${number(stop.opacity)}"/>`).join("");
+ const id = svgPaintId(paint, context);
+ if (paint.kind === "radial-gradient") {
+ return [`<radialGradient id="${id}" cx="${number(paint.center.x * 100)}%" cy="${number(paint.center.y * 100)}%" r="70.710678%">${stops}</radialGradient>`];
+ }
+ const radians = (paint.angleDeg - 90) * Math.PI / 180;
+ const x = Math.cos(radians) * 50;
+ const y = Math.sin(radians) * 50;
+ return [`<linearGradient id="${id}" x1="${number(50 - x)}%" y1="${number(50 - y)}%" x2="${number(50 + x)}%" y2="${number(50 + y)}%">${stops}</linearGradient>`];
+ }).join("");
+}
+
+function svgGlyphLayerCss(paint: GlyphPaintLayer | undefined, context: TextRenderContext): string[] {
+ if (paint === undefined) return ["fill:transparent", "stroke:none", "filter:none"];
+ if (paint.kind === "fill") return [`fill:${svgPaintValue(paint.paint, context)}`, "stroke:none", "filter:none"];
+ // The same morphology/filter definition used by flow Text gives Path Text
+ // exact inside/center/outside rings, spread, blur and ordered effects. A
+ // gradient effect is deliberately materialized rather than approximated.
+ glyphFilterDefinition(paint, context);
+ return ["fill:#ffffff", "stroke:none", `filter:url(#${glyphFilterId(paint, context)})`];
+}
+
+function pathPaintLayerCount(element: VisualPathTextElement): number {
+ let count = glyphPaintLayers(element.paints).length;
+ const inspect = (paints: readonly VisualTextPaintLayer[] | undefined): void => {
+ for (const paint of paints ?? []) {
+ if (paint.kind === "box") {
+ throw new Error("HyperFrames Path Text requires Box Paint to be materialized by its owning package.");
+ }
+ }
+ count = Math.max(count, glyphPaintLayers(paints ?? []).length);
+ };
+ inspect(element.paints);
+ for (const paragraph of element.document.paragraphs) {
+ inspect(paragraph.style?.paints);
+ for (const inline of paragraph.inlines) if (inline.kind === "text") inspect(inline.style?.paints);
+ }
+ return Math.max(1, count);
+}
+
+function renderPathDocument(element: VisualPathTextElement, context: TextRenderContext, layerIndex: number): string {
+ const indices: UnitIndices = { paragraph: 0, run: 0, word: 0, grapheme: 0 };
+ return element.document.paragraphs.map((paragraph, paragraphPosition) => {
+ const paragraphIndex = indices.paragraph++;
+ const paragraphTypography = mergedTypography(element.typography, paragraph.style);
+ const paragraphPaints = paragraph.style?.paints ?? element.paints;
+ const content = paragraph.inlines.map((inline) => {
+ if (inline.kind === "break") return " ";
+ const runIndex = indices.run++;
+ const typography = mergedTypography(paragraphTypography, inline.style);
+ const paints = inline.style?.paints ?? paragraphPaints;
+ const paint = glyphPaintLayers(paints)[layerIndex];
+ const text = segmentRun(inline.text, inline.language ?? typography.language).map((segment) => {
+ if (!segment.wordLike) return graphemes(segment.text, inline.language ?? typography.language).map((value) => {
+ const index = indices.grapheme++;
+ return `<tspan data-svml-text-unit-grapheme="${index}"${styleAttribute(unitAnimationCss(element, "grapheme", index, context), context.escape)}>${context.escape(value)}</tspan>`;
+ }).join("");
+ const word = indices.word++;
+ const value = graphemes(segment.text, inline.language ?? typography.language).map((item) => {
+ const index = indices.grapheme++;
+ return `<tspan data-svml-text-unit-grapheme="${index}"${styleAttribute(unitAnimationCss(element, "grapheme", index, context), context.escape)}>${context.escape(item)}</tspan>`;
+ }).join("");
+ return `<tspan data-svml-text-unit-word="${word}"${styleAttribute(unitAnimationCss(element, "word", word, context), context.escape)}>${value}</tspan>`;
+ }).join("");
+ const style = [...typographyCss(typography, context.exactFontFamily), ...svgGlyphLayerCss(paint, context), ...unitAnimationCss(element, "run", runIndex, context)];
+ return `<tspan data-svml-text-unit-run="${runIndex}" ${textLanguageAttributes(typography, context.escape, inline.language, inline.direction)}${styleAttribute(style, context.escape)}>${text}</tspan>`;
+ }).join("");
+ const separator = paragraphPosition === 0 ? "" : " ";
+ return `${separator}<tspan data-svml-text-unit-paragraph="${paragraphIndex}"${styleAttribute(unitAnimationCss(element, "paragraph", paragraphIndex, context), context.escape)}>${content}</tspan>`;
+ }).join("");
+}
+
+export function renderTerminalTextElement(element: TerminalTextElement, context: TextRenderContext): string {
+ assertTextUnitRanges(element);
+ const clockAttributes = `data-svml-text-clock data-svml-text-start-frame="${context.presentStartFrame}" data-svml-text-frame-numerator="${context.programNumerator}" data-svml-text-frame-denominator="${context.programDenominator}"`;
+ const sequenceAttributes = element.sequences.length === 0 ? "" : ` data-svml-text-sequences="${context.escape(JSON.stringify(element.sequences))}" data-svml-text-duration-frames="${context.durationFrames}"`;
+ if (element.kind === "path-text") {
+ const pathId = context.stableId([context.trackId, context.presentId, element.id, "path"]);
+ const anchor = element.align === "start" ? "start" : element.align === "end" ? "end" : "middle";
+ const offset = element.marginAnimation?.keyframes[0]?.startMarginPx
+ ?? (element.align === "start" ? element.startMarginPx : element.align === "end" ? "100%" : "50%");
+ const placementData = element.marginAnimation === undefined
+ ? ` data-svml-text-path-placement="${context.escape(JSON.stringify({
+ align: element.align, startMarginPx: element.startMarginPx, endMarginPx: element.endMarginPx,
+ }))}"`
+ : ` data-svml-text-path-margin="${context.escape(JSON.stringify({
+ startFrame: context.presentStartFrame,
+ numerator: context.programNumerator,
+ denominator: context.programDenominator,
+ align: element.align,
+ endMarginPx: element.endMarginPx,
+ keyframes: element.marginAnimation.keyframes,
+ }))}"`;
+ const layerCount = pathPaintLayerCount(element);
+ const layers = Array.from({ length: layerCount }, (_, layerIndex) => {
+ const textCss = [...typographyCss(element.typography, context.exactFontFamily), "fill:transparent", "stroke:none"].join(";");
+ return `<text aria-hidden="${layerIndex === layerCount - 1 ? "false" : "true"}" data-svml-text-path-paint-layer="${layerIndex}" style="${context.escape(textCss)}" text-anchor="${anchor}" dominant-baseline="central"><textPath href="#${pathId}" startOffset="${typeof offset === "number" ? number(offset) : offset}" side="${element.side}"${placementData}${element.orientation === "upright" ? ' data-svml-text-path-upright="true"' : ""}>${renderPathDocument(element, context, layerIndex)}</textPath></text>`;
+ }).join("");
+ return `<svg ${context.commonAttributes} ${clockAttributes}${sequenceAttributes} ${textLanguageAttributes(element.typography, context.escape)} width="100%" height="100%" style="${context.escape(`${context.baseStyle};overflow:${element.overflow === "clip" ? "hidden" : "visible"}`)}"><defs><path id="${pathId}" d="${context.escape(pathData(element.reverse ? reversePath(element.path) : element.path))}"/>${svgPaintDefinitions(element, context)}${glyphFilterDefinitions(element, context)}</defs>${layers}</svg>`;
+ }
+ const rootStyle = [
+ context.baseStyle,
+ "display:flex",
+ `align-items:${element.flow.blockAlign === "start" ? "flex-start" : element.flow.blockAlign === "end" ? "flex-end" : "center"}`,
+ `justify-content:${element.flow.inlineAlign === "start" ? "flex-start" : element.flow.inlineAlign === "end" ? "flex-end" : "center"}`,
+ ...(element.flow.clipToFrame ? ["overflow:hidden"] : []),
+ ...boxCss(element.paints, "frame"),
+ ];
+ const contentStyle = [
+ "position:relative",
+ ...flowCss(element),
+ ...typographyCss(element.typography, context.exactFontFamily),
+ ...inheritedGlyphColor(element.paints),
+ ...boxCss(element.paints, "content"),
+ ];
+ const lineSequences = element.sequences.filter((sequence) => sequence.unit === "line");
+ const layoutData = [
+ `data-svml-text-overflow="${element.flow.overflow}"`,
+ `data-svml-text-writing-mode="${element.typography.writingMode}"`,
+ ...(element.flow.minimumScale === undefined ? [] : [`data-svml-text-minimum-scale="${number(element.flow.minimumScale)}"`]),
+ ...(element.flow.maxLines === undefined ? [] : [`data-svml-text-max-lines="${element.flow.maxLines}"`]),
+ ].join(" ");
+ const lineData = lineSequences.length === 0 ? "" : ` data-svml-text-line-sequences="${context.escape(JSON.stringify(lineSequences))}"`;
+ return `<div ${context.commonAttributes} ${clockAttributes}${sequenceAttributes} ${textLanguageAttributes(element.typography, context.escape)} style="${context.escape(rootStyle.join(";"))}">${glyphPaintDefinitions(element, context)}${tailHtml(element.paints, "frame", context)}<div data-svml-text-flow ${layoutData}${lineData}${styleAttribute(contentStyle, context.escape)}>${tailHtml(element.paints, "content", context)}${renderDocument(element.document, element, context)}</div></div>`;
+}
+
+export function collectTerminalTextFonts(element: TerminalTextElement): FontArtifactRef[] {
+ const result: FontArtifactRef[] = [...(element.typography.fonts ?? [])];
+ for (const paragraph of element.document.paragraphs) {
+ result.push(...(paragraph.style?.typography?.fonts ?? []));
+ for (const inline of paragraph.inlines) {
+ if (inline.kind === "text") result.push(...(inline.style?.typography?.fonts ?? []));
+ }
+ }
+ const unique = new Map(result.map((font) => [digestOf(font), font]));
+ return [...unique.values()];
+}
+
+/** Renderer-owned deterministic post-layout step for physical-line selectors. */
+export const terminalTextLayoutScript = String.raw`
+const svmlTextEase = (name, value) => {
+ if (name === 'ease-in') return value * value;
+ if (name === 'ease-out') return 1 - (1 - value) * (1 - value);
+ if (name === 'ease-in-out') return value < 0.5 ? 2 * value * value : 1 - Math.pow(-2 * value + 2, 2) / 2;
+ return value;
+};
+const svmlUpdateUprightTextPaths = () => {
+ for (const path of document.querySelectorAll('[data-svml-text-path-upright]')) {
+ for (const glyph of path.querySelectorAll('[data-svml-text-unit-grapheme]')) {
+ try {
+ glyph.removeAttribute('rotate');
+ const pathRotation = glyph.getRotationOfChar(0);
+ glyph.setAttribute('rotate', String(-pathRotation));
+ } catch (error) {
+ throw new Error('Upright Path Text could not resolve exact glyph orientation.', { cause: error });
+ }
+ }
+ }
+};
+const svmlUpdateStaticTextPathPlacements = () => {
+ for (const textPath of document.querySelectorAll('[data-svml-text-path-placement]')) {
+ const data = JSON.parse(textPath.getAttribute('data-svml-text-path-placement'));
+ const href = textPath.getAttribute('href');
+ const path = href && document.getElementById(href.slice(1));
+ if (!path || typeof path.getTotalLength !== 'function') throw new Error('Path Text cannot resolve its owned vector path.');
+ const length = path.getTotalLength();
+ const start = data.startMarginPx;
+ const end = length - data.endMarginPx;
+ if (end < start) throw new Error('Path Text margins exceed the owned path length.');
+ textPath.setAttribute('startOffset', String(data.align === 'start' ? start : data.align === 'end' ? end : (start + end) / 2));
+ }
+};
+const svmlUpdateTextPathMargins = (time) => {
+ for (const path of document.querySelectorAll('[data-svml-text-path-margin]')) {
+ const data = JSON.parse(path.getAttribute('data-svml-text-path-margin'));
+ const frames = data.keyframes;
+ // HyperFrames may reach the same source frame through an incremental seek
+ // or a fresh worker seek. Quantize the absolute clock back to the authored
+ // integer frame before evaluating package-owned motion so both routes are
+ // byte-identical.
+ const local = Math.round(time * data.numerator / data.denominator - data.startFrame);
+ let value = frames[0].startMarginPx;
+ if (local >= frames[frames.length - 1].atFrame) value = frames[frames.length - 1].startMarginPx;
+ else {
+ for (let index = 0; index < frames.length - 1; index += 1) {
+ const left = frames[index];
+ const right = frames[index + 1];
+ if (local < left.atFrame || local > right.atFrame) continue;
+ const progress = svmlTextEase(left.easing || 'linear', (local - left.atFrame) / (right.atFrame - left.atFrame));
+ value = left.startMarginPx + (right.startMarginPx - left.startMarginPx) * progress;
+ break;
+ }
+ }
+ const href = path.getAttribute('href');
+ const geometry = href && document.getElementById(href.slice(1));
+ if (!geometry || typeof geometry.getTotalLength !== 'function') throw new Error('Animated Path Text cannot resolve its owned vector path.');
+ const end = geometry.getTotalLength() - data.endMarginPx;
+ if (end < value) throw new Error('Animated Path Text margins exceed the owned path length.');
+ path.setAttribute('startOffset', String(data.align === 'start' ? value : data.align === 'end' ? end : (value + end) / 2));
+ }
+ svmlUpdateUprightTextPaths();
+};
+const svmlTextUnitBaseStyles = new WeakMap();
+const svmlTextAnimatedStyleNames = ['-webkit-text-fill-color', '-webkit-text-stroke-color', 'background-color', 'color', 'filter', 'opacity', 'transform'];
+const svmlTextPropertyName = (name) => {
+ if (name === '-webkit-text-fill-color') return 'webkitTextFillColor';
+ if (name === '-webkit-text-stroke-color') return 'webkitTextStrokeColor';
+ if (name === 'background-color') return 'backgroundColor';
+ return name;
+};
+const svmlTextSeededOrder = (length, seed) => {
+ const result = Array.from({ length }, (_, index) => index);
+ let state = seed >>> 0;
+ for (let index = result.length - 1; index > 0; index -= 1) {
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+ const selected = state % (index + 1);
+ [result[index], result[selected]] = [result[selected], result[index]];
+ }
+ return result;
+};
+const svmlTextSequenceRank = (sequence, index) => {
+ if (index < sequence.range.start || index >= sequence.range.endExclusive) return null;
+ const length = sequence.range.endExclusive - sequence.range.start;
+ const local = index - sequence.range.start;
+ if (sequence.order === 'forward') return local;
+ if (sequence.order === 'reverse') return length - 1 - local;
+ return svmlTextSeededOrder(length, sequence.seed || 0).indexOf(local);
+};
+const svmlTextSequenceClock = (sequence, rank, frame) => {
+ const start = sequence.startFrame + rank * sequence.staggerFrames;
+ const end = start + sequence.unitDurationFrames * sequence.cycles;
+ if (frame <= start) return 0;
+ if (frame >= end) return sequence.unitDurationFrames;
+ // Every cycle is a half-open interval. At an exact cycle boundary the next
+ // cycle begins at progress zero; the result therefore depends only on this
+ // absolute authored frame, never on which partition rendered the previous
+ // frame. A repeated keyframe-offset list cannot express that law reliably
+ // across fresh and incrementally-seeked browser animation instances.
+ return (frame - start) % sequence.unitDurationFrames;
+};
+const svmlTextSequenceProgress = (sequence, clock) => {
+ const progress = clock / sequence.unitDurationFrames;
+ let left = sequence.keyframes[0];
+ let right = sequence.keyframes[sequence.keyframes.length - 1];
+ for (let index = 0; index < sequence.keyframes.length - 1; index += 1) {
+ if (progress < sequence.keyframes[index].atProgress || progress > sequence.keyframes[index + 1].atProgress) continue;
+ left = sequence.keyframes[index];
+ right = sequence.keyframes[index + 1];
+ break;
+ }
+ const width = right.atProgress - left.atProgress;
+ return {
+ left,
+ right,
+ progress: svmlTextEase(left.easing || 'linear', width <= 0 ? 1 : (progress - left.atProgress) / width),
+ };
+};
+const svmlSeekTextUnitAnimations = (time) => {
+ const unitSelector = '[data-svml-text-unit-paragraph],[data-svml-text-unit-run],[data-svml-text-unit-word],[data-svml-text-unit-grapheme]';
+ for (const root of document.querySelectorAll('[data-svml-text-clock][data-svml-text-sequences]')) {
+ const startFrame = Number(root.getAttribute('data-svml-text-start-frame'));
+ const numerator = Number(root.getAttribute('data-svml-text-frame-numerator'));
+ const denominator = Number(root.getAttribute('data-svml-text-frame-denominator'));
+ const durationFrames = Number(root.getAttribute('data-svml-text-duration-frames'));
+ if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)
+ || !Number.isSafeInteger(durationFrames) || numerator <= 0 || denominator <= 0 || durationFrames <= 0) {
+ throw new Error('Invalid terminal Text animation clock.');
+ }
+ const sequences = JSON.parse(root.getAttribute('data-svml-text-sequences') || '[]');
+ const localFrame = Math.max(0, Math.min(durationFrames, Math.round(time * numerator / denominator - startFrame)));
+ for (const unit of root.querySelectorAll(unitSelector)) {
+ let base = svmlTextUnitBaseStyles.get(unit);
+ if (!base) {
+ base = Object.fromEntries(svmlTextAnimatedStyleNames.map((name) => [name, unit.style.getPropertyValue(name)]));
+ svmlTextUnitBaseStyles.set(unit, base);
+ }
+ for (const name of svmlTextAnimatedStyleNames) {
+ if (base[name]) unit.style.setProperty(name, base[name]);
+ else unit.style.removeProperty(name);
+ }
+ for (const sequence of sequences) {
+ const attribute = sequence.unit === 'line' ? 'data-svml-text-physical-line' : 'data-svml-text-unit-' + sequence.unit;
+ if (!unit.hasAttribute(attribute)) continue;
+ const index = Number(unit.getAttribute(attribute));
+ const rank = Number.isSafeInteger(index) ? svmlTextSequenceRank(sequence, index) : null;
+ if (rank === null) continue;
+ const clock = svmlTextSequenceClock(sequence, rank, localFrame);
+ const keyframes = sequence.keyframes.map((point) => {
+ const frame = { offset: point.atProgress, ...(point.easing ? { easing: point.easing } : {}) };
+ for (const declaration of point.style) frame[svmlTextPropertyName(declaration.name)] = declaration.value;
+ return frame;
+ });
+ const nativeAnimate = Element.prototype.__hfOriginalAnimate;
+ const animation = typeof nativeAnimate === 'function'
+ ? nativeAnimate.call(unit, keyframes, { duration: sequence.unitDurationFrames, fill: 'both', iterations: 1 })
+ : unit.animate(keyframes, { duration: sequence.unitDurationFrames, fill: 'both', iterations: 1 });
+ animation.pause();
+ animation.currentTime = clock;
+ const animatedNames = [...new Set(sequence.keyframes.flatMap((keyframe) => keyframe.style.map((declaration) => declaration.name)))];
+ const computed = getComputedStyle(unit);
+ const sampled = Object.fromEntries(animatedNames.map((name) => [name, computed.getPropertyValue(name)]));
+ animation.cancel();
+ if (animatedNames.includes('opacity')) {
+ const { left, right, progress } = svmlTextSequenceProgress(sequence, clock);
+ const leftValue = left.style.find((declaration) => declaration.name === 'opacity')?.value;
+ const rightValue = right.style.find((declaration) => declaration.name === 'opacity')?.value;
+ if (typeof leftValue === 'number' && typeof rightValue === 'number') sampled.opacity = String(leftValue + (rightValue - leftValue) * progress);
+ }
+ for (const name of animatedNames) unit.style.setProperty(name, sampled[name]);
+ }
+ }
+ }
+};
+const svmlTextComposition = document.querySelector('[data-composition-id]');
+if (!svmlTextComposition) throw new Error('Terminal Text could not resolve the containing HyperFrames composition.');
+const svmlTextCompositionId = svmlTextComposition.getAttribute('data-composition-id');
+if (!svmlTextCompositionId) throw new Error('Terminal Text composition identity is empty.');
+let svmlTextAbsoluteTime = 0;
+let svmlTextReady = false;
+const svmlTextTimeline = {
+ pause() { return this; },
+ seek(time) { return this.totalTime(time); },
+ totalTime(time) {
+ if (time === undefined) return svmlTextAbsoluteTime;
+ // Register and remember seeks synchronously, even while exact fonts are
+ // still loading. A worker may begin at any frame; once layout becomes
+ // ready the latest requested absolute frame is evaluated exactly once.
+ svmlTextAbsoluteTime = Math.max(0, Number(time) || 0);
+ if (svmlTextReady) {
+ svmlSeekTextUnitAnimations(svmlTextAbsoluteTime);
+ svmlUpdateTextPathMargins(svmlTextAbsoluteTime);
+ // Attribute changes on SVG text paths and browser text layout are
+ // sampled synchronously for the exact authored frame. Do not wait for a
+ // requestAnimationFrame from HyperFrames' seek barrier: capture is
+ // paused behind that barrier, so doing so would deadlock both clocks.
+ document.documentElement.getBoundingClientRect();
+ }
+ return this;
+ },
+};
+window.__timelines = window.__timelines || {};
+window.__timelines[svmlTextCompositionId] = svmlTextTimeline;
+if (typeof window.__hfForceTimelineRebind === 'function') window.__hfForceTimelineRebind();
+const svmlTextLayoutReady = document.fonts.ready.then(() => {
+ svmlUpdateStaticTextPathPlacements();
+ svmlUpdateUprightTextPaths();
+ const physicalLines = (flow) => {
+ const values = [];
+ const vertical = flow.getAttribute('data-svml-text-writing-mode') !== 'horizontal-tb';
+ for (const glyph of flow.querySelectorAll('[data-svml-text-unit-grapheme]')) {
+ const rect = glyph.getBoundingClientRect();
+ const axis = vertical ? rect.left : rect.top;
+ if (!values.some((value) => Math.abs(value - axis) < 0.5)) values.push(axis);
+ }
+ return values;
+ };
+ for (const flow of document.querySelectorAll('[data-svml-text-flow][data-svml-text-overflow="ellipsis"]')) {
+ if (flow.getAttribute('data-svml-text-max-lines') || getComputedStyle(flow).whiteSpace === 'pre') continue;
+ const parent = flow.parentElement;
+ if (!parent) throw new Error('Ellipsis Text has no placement frame.');
+ const vertical = flow.getAttribute('data-svml-text-writing-mode') !== 'horizontal-tb';
+ const boundary = parent.getBoundingClientRect();
+ const groups = [];
+ for (const glyph of flow.querySelectorAll('[data-svml-text-unit-grapheme]')) {
+ const rect = glyph.getBoundingClientRect();
+ const axis = vertical ? rect.left : rect.top;
+ let group = groups.find((item) => Math.abs(item.axis - axis) < 0.5);
+ if (!group) { group = { axis, rects: [] }; groups.push(group); }
+ group.rects.push(rect);
+ }
+ const visible = groups.filter((group) => group.rects.some((rect) => vertical
+ ? rect.left >= boundary.left - 0.5 && rect.right <= boundary.right + 0.5
+ : rect.top >= boundary.top - 0.5 && rect.bottom <= boundary.bottom + 0.5)).length;
+ flow.style.webkitLineClamp = String(Math.max(1, visible));
+ }
+ for (const flow of document.querySelectorAll('[data-svml-text-flow][data-svml-text-overflow="shrink"]')) {
+ const minimum = Number(flow.getAttribute('data-svml-text-minimum-scale'));
+ const maximumLines = Number(flow.getAttribute('data-svml-text-max-lines') || '0');
+ const parent = flow.parentElement;
+ if (!parent || !Number.isFinite(minimum) || minimum <= 0 || minimum > 1) throw new Error('Invalid bounded Text shrink request.');
+ const availableWidth = parent.clientWidth;
+ const availableHeight = parent.clientHeight;
+ const apply = (scale) => {
+ flow.style.position = 'absolute';
+ flow.style.left = '0';
+ flow.style.top = '0';
+ flow.style.zoom = '';
+ flow.style.transformOrigin = 'top left';
+ flow.style.transform = 'scale(' + scale + ')';
+ flow.style.width = String(100 / scale) + '%';
+ flow.style.height = String(100 / scale) + '%';
+ };
+ const measure = (scale) => {
+ apply(scale);
+ const lines = physicalLines(flow).length;
+ const boundary = parent.getBoundingClientRect();
+ const glyphRects = [...flow.querySelectorAll('[data-svml-text-unit-grapheme]')]
+ .map((glyph) => glyph.getBoundingClientRect());
+ const left = glyphRects.length === 0 ? boundary.left : Math.min(...glyphRects.map((rect) => rect.left));
+ const right = glyphRects.length === 0 ? boundary.left : Math.max(...glyphRects.map((rect) => rect.right));
+ const top = glyphRects.length === 0 ? boundary.top : Math.min(...glyphRects.map((rect) => rect.top));
+ const bottom = glyphRects.length === 0 ? boundary.top : Math.max(...glyphRects.map((rect) => rect.bottom));
+ const width = right - left;
+ const height = bottom - top;
+ return {
+ fits: left >= boundary.left - 0.5
+ && right <= boundary.right + 0.5
+ && top >= boundary.top - 0.5
+ && bottom <= boundary.bottom + 0.5
+ && (maximumLines === 0 || lines <= maximumLines),
+ width, height, lines,
+ offsets: {
+ left: left - boundary.left,
+ right: boundary.right - right,
+ top: top - boundary.top,
+ bottom: boundary.bottom - bottom,
+ },
+ };
+ };
+ const minimumMeasurement = measure(minimum);
+ if (!minimumMeasurement.fits) throw new Error('Text cannot fit at its authored minimum scale: '
+ + minimumMeasurement.width.toFixed(2) + 'x' + minimumMeasurement.height.toFixed(2)
+ + ' in ' + availableWidth + 'x' + availableHeight + ', lines=' + minimumMeasurement.lines
+ + ', offsets=' + JSON.stringify(minimumMeasurement.offsets)
+ + (maximumLines === 0 ? '' : ', maxLines=' + maximumLines) + '.');
+ let low = minimum;
+ let high = 1;
+ for (let index = 0; index < 20; index += 1) {
+ const middle = (low + high) / 2;
+ if (measure(middle).fits) low = middle;
+ else high = middle;
+ }
+ apply(low);
+ flow.setAttribute('data-svml-text-shrink-scale', low.toFixed(8));
+ }
+ for (const flow of document.querySelectorAll('[data-svml-text-flow][data-svml-text-line-sequences]')) {
+ const sequences = JSON.parse(flow.getAttribute('data-svml-text-line-sequences') || '[]');
+ const glyphs = [...flow.querySelectorAll('[data-svml-text-unit-grapheme]')];
+ const vertical = flow.getAttribute('data-svml-text-writing-mode') !== 'horizontal-tb';
+ const axes = [];
+ const lineOf = new Map();
+ for (const glyph of glyphs) {
+ const rect = glyph.getBoundingClientRect();
+ const axis = vertical ? rect.left : rect.top;
+ let line = axes.findIndex((value) => Math.abs(value - axis) < 0.5);
+ if (line < 0) { line = axes.length; axes.push(axis); }
+ lineOf.set(glyph, line);
+ }
+ for (const sequence of sequences) {
+ if (sequence.range.endExclusive > axes.length) throw new Error('Text line sequence selects a line that does not exist.');
+ }
+ for (let line = 0; line < axes.length; line += 1) {
+ const members = glyphs.filter((glyph) => lineOf.get(glyph) === line);
+ const rects = members.map((glyph) => glyph.getBoundingClientRect());
+ const left = Math.min(...rects.map((rect) => rect.left));
+ const right = Math.max(...rects.map((rect) => rect.right));
+ const top = Math.min(...rects.map((rect) => rect.top));
+ const bottom = Math.max(...rects.map((rect) => rect.bottom));
+ for (const [memberIndex, glyph] of members.entries()) {
+ const rect = rects[memberIndex];
+ glyph.style.transformOrigin = String((left + right) / 2 - rect.left) + 'px ' + String((top + bottom) / 2 - rect.top) + 'px';
+ glyph.setAttribute('data-svml-text-physical-line', String(line));
+ }
+ }
+ }
+ svmlTextReady = true;
+ svmlTextTimeline.totalTime(svmlTextAbsoluteTime);
+});
+window.addEventListener('hf-seek', (event) => {
+ if (!event?.detail || typeof event.detail.waitUntil !== 'function') return;
+ // HyperFrames requires waitUntil to be registered synchronously while the
+ // seek event is dispatched. The Promise itself waits for exact fonts and
+ // deterministic static layout validation. Per-frame sampling is synchronous
+ // inside the registered timeline and forces layout before it returns. A
+ // rejected layout (for example bounded shrink below the authored minimum)
+ // therefore rejects the render instead of becoming an unobserved Promise.
+ event.detail.waitUntil(svmlTextLayoutReady);
+});
+`;
diff --git a/packages/hyperframes/test/browser-visual.test.ts b/packages/hyperframes/test/browser-visual.test.ts
index 83f93c89..176d371f 100644
--- a/packages/hyperframes/test/browser-visual.test.ts
+++ b/packages/hyperframes/test/browser-visual.test.ts
@@ -9,6 +9,8 @@ import { deflateSync } from "node:zlib";
import { resolveCaptionProgram } from "@narratage/caption";
import type { TimedCaptionProjection } from "@narratage/caption";
import { fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";
+import * as deckTrack from "@narratage/deck-track";
+import type { DepthStackCardLabel } from "@narratage/deck-track";
import { decodeOpenFontFaceSurface } from "@narratage/fonts-open";
import type { CompositableSurfaceRef, FontArtifactRef } from "@narratage/media";
import * as mediaTrack from "@narratage/media-track";
@@ -21,6 +23,7 @@ import {
} from "@narratage/hyperframes";
import type { BlobRef, Digest } from "@narratage/protocol";
import { captionDisplaySequence, parseScript } from "@narratage/script";
+import * as rankingTrack from "@narratage/ranking";
import {
appendProgramScreenOverlay,
createScreenOverlaySet,
@@ -32,6 +35,16 @@ import {
import type { ScreenOverlayComponent, ScreenOverlaySet } from "@narratage/screen-overlay";
import { sealCanvasSpace } from "@narratage/spatial";
import type { SvsRecipe } from "@narratage/svs";
+import {
+ renderTextMaskTrack,
+ renderTextTrack,
+ sealTextMaskSpec,
+ sealTextMotion,
+ sealTextStyle,
+ sealTextTrackProgram,
+ stillTextMotion,
+} from "@narratage/text-track";
+import type { TextStyle } from "@narratage/text-track";
const enabled = process.env.SVML_BROWSER_TESTS === "1";
const localFont = process.env.SVML_TEST_FONT_PATH
@@ -150,7 +163,7 @@ async function collectPngs(directory: string): Promise<string[]> {
function yellowPixelsByColumns(file: string, width: number, height: number, columns: number): number[] {
const decoded = spawnSync("ffmpeg", [
"-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1",
- ], { encoding: "buffer", timeout: 30_000 });
+ ], { encoding: "buffer", timeout: 30_000, maxBuffer: Math.max(16 * 1024 * 1024, width * height * 4 + 1024) });
assert.equal(decoded.status, 0, decoded.stderr.toString());
assert.equal(decoded.stdout.byteLength, width * height * 4);
const counts = Array.from({ length: columns }, () => 0);
@@ -168,7 +181,7 @@ function yellowPixelsByColumns(file: string, width: number, height: number, colu
function decodedRgba(file: string, width: number, height: number): Buffer {
const decoded = spawnSync("ffmpeg", [
"-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1",
- ], { encoding: "buffer", timeout: 30_000 });
+ ], { encoding: "buffer", timeout: 30_000, maxBuffer: Math.max(16 * 1024 * 1024, width * height * 4 + 1024) });
assert.equal(decoded.status, 0, decoded.stderr.toString());
assert.equal(decoded.stdout.byteLength, width * height * 4);
return decoded.stdout;
@@ -190,6 +203,57 @@ function matchingPixels(
return count;
}
+function rgbaDifference(left: Buffer, right: Buffer): {
+ readonly pixels: number;
+ readonly channels: number;
+ readonly maximum: number;
+ readonly total: number;
+} {
+ assert.equal(left.byteLength, right.byteLength);
+ let pixels = 0;
+ let channels = 0;
+ let maximum = 0;
+ let total = 0;
+ for (let index = 0; index < left.byteLength; index += 4) {
+ let changed = false;
+ for (let channel = 0; channel < 4; channel += 1) {
+ const delta = Math.abs(left[index + channel]! - right[index + channel]!);
+ if (delta === 0) continue;
+ changed = true;
+ channels += 1;
+ maximum = Math.max(maximum, delta);
+ total += delta;
+ }
+ if (changed) pixels += 1;
+ }
+ return { pixels, channels, maximum, total };
+}
+
+function matchingBounds(
+ rgba: Buffer,
+ width: number,
+ region: { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number },
+ predicate: (red: number, green: number, blue: number, alpha: number) => boolean,
+): { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number } | undefined {
+ let left = region.right;
+ let top = region.bottom;
+ let right = region.left;
+ let bottom = region.top;
+ let found = false;
+ for (let y = region.top; y < region.bottom; y += 1) {
+ for (let x = region.left; x < region.right; x += 1) {
+ const index = (y * width + x) * 4;
+ if (!predicate(rgba[index]!, rgba[index + 1]!, rgba[index + 2]!, rgba[index + 3]!)) continue;
+ found = true;
+ left = Math.min(left, x);
+ top = Math.min(top, y);
+ right = Math.max(right, x + 1);
+ bottom = Math.max(bottom, y + 1);
+ }
+ }
+ return found ? { left, top, right, bottom } : undefined;
+}
+
function longestHorizontalRun(
rgba: Buffer,
width: number,
@@ -660,6 +724,561 @@ test("installed open fonts render CJK, emoji and independent stroke, shadow and
}
});
+test("complete Text flow, Path, local mask and motion stay exact under parallel browser rendering", {
+ skip: !enabled,
+ timeout: 180_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-text-complete-"));
+ try {
+ const width = 960;
+ const height = 720;
+ const fps = 12;
+ const frames = 12;
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: 1,
+ frameRate: { numerator: fps, denominator: 1 },
+ });
+ const installed = await Promise.all([
+ installedOpenFont("inter", 700, "normal"),
+ installedOpenFont("noto-sans-sc", 700, "normal"),
+ installedOpenFont("noto-color-emoji", 400, "normal"),
+ ]);
+ const fonts = installed.map(({ font }) => font);
+ const fontBytes = new Map<Digest, Uint8Array>();
+ for (const face of installed) for (const [artifactDigest, bytes] of face.bytes) fontBytes.set(artifactDigest, bytes);
+ const flow = {
+ inlineSize: "fixed" as const, blockSize: "fixed" as const,
+ paddingPx: { inlineStart: 8, inlineEnd: 8, blockStart: 6, blockEnd: 6 },
+ inlineAlign: "center" as const, blockAlign: "center" as const,
+ wrap: "word" as const, overflow: "visible" as const,
+ clipToFrame: false, columns: 1, columnGapPx: 0,
+ metricEdge: "line-box" as const,
+ };
+ const baseStyle = (id: string, stackingOrder: number, paints: TextStyle["paints"]): TextStyle => sealTextStyle({
+ contract: "svml.text-style@1", id, stackingOrder,
+ typography: {
+ fonts, sizePx: 42, weight: 700, style: "normal", axes: [], features: [],
+ synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+ lineHeight: 1.1, language: "en", direction: "auto", writingMode: "horizontal-tb",
+ baselineShiftPx: 0, tabSize: 4, indentationPx: 0, paragraphBeforePx: 0,
+ paragraphAfterPx: 0, transform: "none", variantCaps: "normal", verticalAlign: "baseline",
+ decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints,
+ area: flow,
+ point: { anchorInline: "center", anchorBlock: "center" },
+ path: {
+ side: "left", orientation: "upright", startMarginPx: 10, endMarginPx: 10,
+ align: "center", reverse: false, overflow: "visible",
+ },
+ });
+ const plain = baseStyle("plain", 20, [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }]);
+ const decorated = sealTextStyle({
+ ...baseStyle("decorated", 30, [
+ { kind: "shadow", paint: { kind: "solid", color: "#2563eb" }, offsetX: 8, offsetY: 6, blurPx: 2, spreadPx: 1 },
+ { kind: "stroke", paint: { kind: "solid", color: "#ef4444" }, widthPx: 4, placement: "outside" },
+ { kind: "fill", paint: { kind: "linear-gradient", angleDeg: 90, stops: [
+ { offset: 0, color: "#ffffff", opacity: 1 }, { offset: 1, color: "#67e8f9", opacity: 1 },
+ ] } },
+ { kind: "stroke", paint: { kind: "solid", color: "#fde047" }, widthPx: 2, placement: "inside" },
+ { kind: "shadow", paint: { kind: "solid", color: "#16a34a" }, offsetX: -5, offsetY: 4, blurPx: 0, spreadPx: 0 },
+ { kind: "glow", paint: { kind: "solid", color: "#d946ef" }, blurPx: 7, spreadPx: 2 },
+ {
+ kind: "box", target: "line", continuity: "isolated",
+ decoration: {
+ fill: { kind: "solid", color: "#111827cc" },
+ paddingPx: { top: 3, right: 6, bottom: 3, left: 6 },
+ radiiPx: { topLeft: 6, topRight: 6, bottomRight: 6, bottomLeft: 6 }, shadows: [],
+ },
+ },
+ ]),
+ typography: {
+ ...plain.typography,
+ decorations: [{ line: "underline", paint: { kind: "solid", color: "#facc15" }, style: "solid", thicknessPx: 2, offsetPx: 3, skipInk: true }],
+ },
+ });
+ const clip = sealTextStyle({ ...plain, id: "clip", area: { ...flow, overflow: "clip", clipToFrame: true }, typography: { ...plain.typography, sizePx: 52 } });
+ const ellipsis = sealTextStyle({ ...plain, id: "ellipsis", area: { ...flow, overflow: "ellipsis", maxLines: 2, clipToFrame: true }, typography: { ...plain.typography, sizePx: 32 } });
+ const shrink = sealTextStyle({ ...plain, id: "shrink", area: { ...flow, overflow: "shrink", maxLines: 3, minimumScale: 0.25, clipToFrame: true }, typography: { ...plain.typography, sizePx: 40 } });
+ const pathStyle = sealTextStyle({
+ ...plain,
+ id: "path",
+ stackingOrder: 40,
+ typography: { ...plain.typography, sizePx: 38 },
+ paints: [{ kind: "fill", paint: {
+ kind: "radial-gradient", center: { x: 0.35, y: 0.5 }, stops: [
+ { offset: 0, color: "#ffffff", opacity: 1 },
+ { offset: 1, color: "#22d3ee", opacity: 1 },
+ ],
+ } }],
+ path: { ...plain.path, orientation: "upright", align: "center" },
+ });
+ const animated = sealTextMotion({
+ contract: "svml.text-motion@1", id: "animated",
+ item: { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(25px)" }] },
+ { atFrame: 4, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ { atFrame: 8, style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ { atFrame: frames, easing: "ease-in", style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(-20px)" }] },
+ ] },
+ sequences: [{
+ id: "reverse-words", unit: "word", range: { start: 0, endExclusive: 3 }, order: "reverse",
+ startFrame: 0, unitDurationFrames: 4, staggerFrames: 2, cycles: 1,
+ keyframes: [
+ { atProgress: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "scale(0.5)" }] },
+ { atProgress: 1, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "scale(1)" }] },
+ ],
+ }],
+ });
+ const pathMotion = sealTextMotion({
+ contract: "svml.text-motion@1", id: "path-motion", sequences: [],
+ pathMargin: { keyframes: [{ atFrame: 0, startMarginPx: 20 }, { atFrame: frames, startMarginPx: 150, easing: "ease-in-out" }] },
+ });
+ const textProgram = sealTextTrackProgram({
+ contract: "svml.text-track-program@1", id: "complete-text",
+ items: [
+ {
+ id: "point", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "point",
+ geometry: { kind: "point", point: { contract: "svml.spatial-point@1", xPx: 160, yPx: 56 } },
+ document: { paragraphs: [{ id: "point-p", inlines: [{ kind: "text", id: "point-r", text: "POINT" }] }] }, style: plain, motion: stillTextMotion(),
+ },
+ {
+ id: "multilingual", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "multilingual",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 20, yPx: 100, widthPx: 300, heightPx: 180 } },
+ document: { paragraphs: [{ id: "multi-p", inlines: [
+ { kind: "text", id: "latin", text: "Intent " },
+ { kind: "text", id: "cjk", text: "可见", language: "zh-Hans" },
+ { kind: "break", id: "multi-break" },
+ { kind: "text", id: "rtl", text: "مرحبا", language: "ar", direction: "rtl" },
+ { kind: "text", id: "emoji", text: " 👩🏽‍💻 e\u0301" },
+ ] }] }, style: decorated, motion: stillTextMotion(),
+ },
+ {
+ id: "clip", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "clip",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 345, yPx: 100, widthPx: 170, heightPx: 80 } },
+ document: { paragraphs: [{ id: "clip-p", inlines: [{ kind: "text", id: "clip-r", text: "CLIPPED CONTENT MUST STAY INSIDE" }] }] }, style: clip, motion: stillTextMotion(),
+ },
+ {
+ id: "ellipsis", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "ellipsis",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 535, yPx: 100, widthPx: 170, heightPx: 80 } },
+ document: { paragraphs: [{ id: "ellipsis-p", inlines: [{ kind: "text", id: "ellipsis-r", text: "ELLIPSIS KEEPS A BOUNDED TWO LINE REGION" }] }] }, style: ellipsis, motion: stillTextMotion(),
+ },
+ {
+ id: "shrink", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "shrink",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 725, yPx: 100, widthPx: 215, heightPx: 100 } },
+ document: { paragraphs: [{ id: "shrink-p", inlines: [{ kind: "text", id: "shrink-r", text: "SHRINK PRESERVES EVERY AUTHORED WORD INSIDE ITS BOUND" }] }] }, style: shrink, motion: stillTextMotion(),
+ },
+ {
+ id: "sequence", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "sequence",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 120, yPx: 490, widthPx: 360, heightPx: 100 } },
+ document: { paragraphs: [{ id: "sequence-p", inlines: [{ kind: "text", id: "sequence-r", text: "ONE TWO THREE" }] }] }, style: plain, motion: animated,
+ },
+ {
+ id: "path", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "path",
+ geometry: { kind: "path", path: { contract: "svml.spatial-path@1", commands: [
+ { kind: "move", xPx: 80, yPx: 390 }, { kind: "cubic", control1X: 300, control1Y: 290, control2X: 650, control2Y: 470, xPx: 900, yPx: 350 },
+ ] } },
+ document: { paragraphs: [{ id: "path-p", inlines: [{ kind: "text", id: "path-r", text: "UPRIGHT PATH TEXT" }] }] }, style: pathStyle, motion: pathMotion,
+ },
+ ],
+ });
+ const textTrack = renderTextTrack(space, textProgram);
+ const maskMaterialBytes = rgbaPng(380, 120, [255, 0, 180, 255]);
+ const maskMaterialDigest = digest(maskMaterialBytes);
+ const maskMaterial: CompositableSurfaceRef = {
+ contract: "svml.compositable-surface@1",
+ artifact: { kind: "blob", digest: maskMaterialDigest, size: maskMaterialBytes.byteLength, mediaType: "image/png" },
+ width: 380, height: 120, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
+ };
+ const maskStyle = sealTextStyle({
+ ...plain,
+ id: "mask-style",
+ stackingOrder: 50,
+ typography: { ...plain.typography, sizePx: 100, lineHeight: 1 },
+ paints: [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }],
+ area: { ...plain.area, wrap: "none" },
+ });
+ const maskTrack = renderTextMaskTrack(space, sealTextTrackProgram({
+ contract: "svml.text-track-program@1", id: "mask-shape",
+ items: [{
+ id: "mask", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: "mask",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 520, yPx: 500, widthPx: 380, heightPx: 120 } },
+ document: { paragraphs: [{ id: "mask-p", inlines: [{ kind: "text", id: "mask-r", text: "MASK" }] }] },
+ style: maskStyle, motion: stillTextMotion(),
+ }],
+ }), maskMaterial, sealTextMaskSpec({
+ contract: "svml.text-mask-spec@1", id: "text-mask", mode: "alpha", materialFit: "cover",
+ }));
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "complete-text-browser",
+ canvas: { width, height, clearColor: "#000000" }, tracks: [textTrack, maskTrack],
+ }), space);
+ assert.match(document.html, /data-svml-text-shrink-scale/u);
+ assert.match(document.html, /data-svml-text-path-upright/u);
+ assert.match(document.html, /mask-type:alpha/u);
+ const paths = new Map<Digest, string>();
+ await Promise.all([...fontBytes].map(async ([artifactDigest, bytes], index) => {
+ const name = `font-${index}.woff2`;
+ await writeFile(path.join(temp, name), bytes);
+ paths.set(artifactDigest, `./${name}`);
+ }));
+ await writeFile(path.join(temp, "mask-material.png"), maskMaterialBytes);
+ paths.set(maskMaterialDigest, "./mask-material.png");
+ await writeFile(path.join(temp, "index.html"), materializeHyperframesHtml(document, (artifact) => {
+ const materialized = paths.get(artifact.digest);
+ if (materialized === undefined) throw new Error(`Unexpected complete-Text Artifact ${artifact.digest}`);
+ return materialized;
+ }));
+ const render = async (workers: number, directory: string): Promise<string[]> => {
+ const output = path.join(temp, directory);
+ await mkdir(output);
+ const result = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", String(fps), "--workers", String(workers),
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 170_000 });
+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+ return await collectPngs(output);
+ };
+ const sequential = await render(1, "sequential");
+ const parallel = await render(3, "parallel");
+ assert.equal(sequential.length, frames);
+ assert.equal(parallel.length, frames);
+ const read = await import("node:fs/promises").then(({ readFile }) => readFile);
+ assert.deepEqual(
+ await Promise.all(sequential.map(async (file) => digest(await read(file)))),
+ await Promise.all(parallel.map(async (file) => digest(await read(file)))),
+ "complete Text changed under partitioned/out-of-order rendering",
+ );
+ const first = decodedRgba(sequential[0]!, width, height);
+ const middle = decodedRgba(sequential[6]!, width, height);
+ const last = decodedRgba(sequential.at(-1)!, width, height);
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 90, right: 330, bottom: 290 }, (r, g, b) => r + g + b > 220) > 500,
+ "multilingual rich Text did not paint");
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 90, right: 330, bottom: 290 }, (r, g, b) => r > 150 && g < 130 && b < 130) > 50,
+ "outside stroke layer did not paint red");
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 90, right: 330, bottom: 290 }, (r, g, b) => b > 130 && r < 150) > 50,
+ "shadow layer did not paint blue");
+ assert.ok(matchingPixels(middle, width, { left: 60, top: 285, right: 920, bottom: 470 }, (r, g, b) => r + g + b > 180) > 150,
+ "Path Text did not paint on its owned path");
+ assert.ok(matchingPixels(middle, width, { left: 60, top: 285, right: 920, bottom: 470 }, (r, g, b) => b > 150 && g > 100 && r < 180) > 30,
+ "Path Text radial gradient did not paint its cyan edge");
+ const pathRegion = { left: 60, top: 285, right: 920, bottom: 470 };
+ const pathInk = (rgba: Buffer) => matchingBounds(rgba, width, pathRegion, (r, g, b) => r > 180 && g > 180 && b > 180);
+ const firstPath = pathInk(first);
+ const lastPath = pathInk(last);
+ assert(firstPath !== undefined && lastPath !== undefined);
+ assert.ok(lastPath.left > firstPath.left + 35,
+ `animated Path Text did not honor its changing start margin: ${JSON.stringify({ firstPath, lastPath })}`);
+ const maskPixels = matchingPixels(middle, width, { left: 520, top: 500, right: 900, bottom: 620 }, (r, _g, b) => r > 100 || b > 100);
+ assert.ok(maskPixels > 1_000, `explicit local Text Mask revealed only ${maskPixels} owned-material pixels`);
+ const sequenceRegion = { left: 110, top: 480, right: 490, bottom: 600 };
+ const visible = (rgba: Buffer) => matchingPixels(rgba, width, sequenceRegion, (r, g, b) => r + g + b > 400);
+ const sequenceCounts = { first: visible(first), middle: visible(middle), last: visible(last) };
+ assert.ok(sequenceCounts.middle > sequenceCounts.first, `item/word sequence did not enter: ${JSON.stringify(sequenceCounts)}`);
+ assert.ok(sequenceCounts.middle > sequenceCounts.last, `item motion did not exit: ${JSON.stringify(sequenceCounts)}`);
+ const outsideClip = { left: 345, top: 180, right: 515, bottom: 240 };
+ assert.equal(matchingPixels(middle, width, outsideClip, (r, g, b) => r + g + b > 50), 0,
+ "clip Text painted outside its authored frame");
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
+test("Text box targets, rich runs and every sequence direction remain stable across workers", {
+ skip: !enabled,
+ timeout: 180_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-text-box-sequence-"));
+ try {
+ const width = 960;
+ const height = 440;
+ const fps = 12;
+ const frames = 12;
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: 1,
+ frameRate: { numerator: fps, denominator: 1 },
+ });
+ const installed = await installedOpenFont("inter", 700, "normal");
+ const fonts = [installed.font];
+ const flow = {
+ inlineSize: "fixed" as const, blockSize: "fixed" as const,
+ paddingPx: { inlineStart: 8, inlineEnd: 8, blockStart: 6, blockEnd: 6 },
+ inlineAlign: "center" as const, blockAlign: "center" as const,
+ wrap: "word" as const, overflow: "visible" as const,
+ clipToFrame: false, columns: 1, columnGapPx: 0, metricEdge: "line-box" as const,
+ };
+ const box = (
+ target: "frame" | "content" | "paragraph" | "line" | "run" | "word" | "grapheme",
+ continuity: "isolated" | "joined",
+ color: string,
+ ): TextStyle["paints"][number] => ({
+ kind: "box", target, continuity,
+ decoration: {
+ fill: { kind: "solid", color },
+ paddingPx: { top: 3, right: 5, bottom: 3, left: 5 },
+ radiiPx: { topLeft: 5, topRight: 5, bottomRight: 5, bottomLeft: 5 },
+ shadows: [],
+ },
+ });
+ const style = (
+ id: string,
+ stackingOrder: number,
+ target: "frame" | "content" | "line" | "word" | "grapheme",
+ continuity: "isolated" | "joined",
+ color: string,
+ ): TextStyle => sealTextStyle({
+ contract: "svml.text-style@1", id, stackingOrder,
+ typography: {
+ fonts, sizePx: 34, weight: 700, style: "normal", axes: [], features: [],
+ synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+ lineHeight: 1.05, language: "en", direction: "auto", writingMode: "horizontal-tb",
+ baselineShiftPx: 0, tabSize: 4, indentationPx: 0, paragraphBeforePx: 0,
+ paragraphAfterPx: 0, transform: "none", variantCaps: "normal", verticalAlign: "baseline",
+ decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [
+ { kind: "fill", paint: { kind: "solid", color: "#ffffff" } },
+ box(target, continuity, color),
+ ...(id === "forward-grapheme" ? [box("paragraph", "isolated", "#312e81")] : []),
+ ],
+ area: flow,
+ point: { anchorInline: "center", anchorBlock: "center" },
+ path: {
+ side: "left", orientation: "follow", startMarginPx: 0, endMarginPx: 0,
+ align: "start", reverse: false, overflow: "visible",
+ },
+ });
+ const cases = [
+ { id: "forward-grapheme", unit: "grapheme", order: "forward", target: "frame", continuity: "isolated", color: "#7f1d1d" },
+ { id: "reverse-grapheme", unit: "grapheme", order: "reverse", target: "content", continuity: "isolated", color: "#166534" },
+ { id: "forward-word", unit: "word", order: "forward", target: "line", continuity: "isolated", color: "#854d0e" },
+ { id: "reverse-word", unit: "word", order: "reverse", target: "word", continuity: "isolated", color: "#1d4ed8" },
+ { id: "forward-line", unit: "line", order: "forward", target: "word", continuity: "joined", color: "#0f766e" },
+ { id: "reverse-line", unit: "line", order: "reverse", target: "grapheme", continuity: "isolated", color: "#a16207" },
+ ] as const;
+ const track = renderTextTrack(space, sealTextTrackProgram({
+ contract: "svml.text-track-program@1", id: "text-box-sequence",
+ items: cases.map((entry, index) => {
+ const lineUnit = entry.unit === "line";
+ const document = index === 1
+ ? { paragraphs: [{ id: `${entry.id}-p`, inlines: [
+ { kind: "text" as const, id: `${entry.id}-base`, text: "NESTED " },
+ {
+ kind: "text" as const, id: `${entry.id}-run`, text: "RUN STYLE WRAPS",
+ style: {
+ typography: { sizePx: 25 },
+ paints: [
+ { kind: "fill" as const, paint: { kind: "solid" as const, color: "#f9a8d4" } },
+ {
+ kind: "box" as const, target: "run" as const, continuity: "isolated" as const,
+ decoration: {
+ fill: { kind: "solid" as const, color: "#4c1d95" },
+ paddingPx: { top: 2, right: 3, bottom: 2, left: 3 },
+ radiiPx: { topLeft: 3, topRight: 3, bottomRight: 3, bottomLeft: 3 }, shadows: [],
+ },
+ },
+ ],
+ },
+ },
+ ] }] }
+ : { paragraphs: [{ id: `${entry.id}-p`, inlines: [
+ { kind: "text" as const, id: `${entry.id}-a`, text: "ALPHA BETA" },
+ ...(lineUnit ? [{ kind: "break" as const, id: `${entry.id}-break` }, { kind: "text" as const, id: `${entry.id}-b`, text: "GAMMA" }] : []),
+ ] }] };
+ return {
+ id: entry.id, sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: frames }, tieBreak: entry.id,
+ geometry: {
+ kind: "area" as const,
+ frame: {
+ contract: "svml.spatial-frame@1" as const,
+ xPx: 10 + (index % 3) * 315, yPx: 10 + Math.floor(index / 3) * 215,
+ widthPx: 305, heightPx: 205,
+ },
+ },
+ document,
+ style: style(entry.id, 10 + index, entry.target, entry.continuity, entry.color),
+ motion: sealTextMotion({
+ contract: "svml.text-motion@1", id: `${entry.id}-motion`,
+ sequences: [{
+ id: `${entry.id}-sequence`, unit: entry.unit,
+ range: { start: 0, endExclusive: lineUnit ? 2 : entry.unit === "word" ? 2 : 5 },
+ order: entry.order, startFrame: 0, unitDurationFrames: 4, staggerFrames: 1,
+ cycles: index === 0 ? 2 : 1,
+ keyframes: [
+ { atProgress: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(7px)" }] },
+ { atProgress: 1, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ ],
+ }],
+ }),
+ };
+ }),
+ }));
+ const compiled = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "text-box-sequence-browser",
+ canvas: { width, height, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ assert.match(compiled.html, /data-svml-text-line-sequences/u);
+ assert.match(compiled.html, /background-image:linear-gradient\(#312e81,#312e81\)/u);
+ assert.match(compiled.html, /order&quot;:&quot;forward/u);
+ assert.match(compiled.html, /order&quot;:&quot;reverse/u);
+ assert.match(compiled.html, /data-svml-text-run="reverse-grapheme-run"/u);
+ const paths = new Map<Digest, string>();
+ let fontIndex = 0;
+ for (const [artifactDigest, bytes] of installed.bytes) {
+ const name = `font-${fontIndex++}.woff2`;
+ await writeFile(path.join(temp, name), bytes);
+ paths.set(artifactDigest, `./${name}`);
+ }
+ await writeFile(path.join(temp, "index.html"), materializeHyperframesHtml(compiled, (artifact) => {
+ const materialized = paths.get(artifact.digest);
+ if (materialized === undefined) throw new Error(`Unexpected Text box Artifact ${artifact.digest}`);
+ return materialized;
+ }));
+ const render = async (workers: number, name: string): Promise<string[]> => {
+ const output = path.join(temp, name);
+ await mkdir(output);
+ const result = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", String(fps), "--workers", String(workers),
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 170_000 });
+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+ return collectPngs(output);
+ };
+ const sequential = await render(1, "sequential");
+ const parallel = await render(3, "parallel");
+ const partitionDifferences = sequential.map((file, index) => rgbaDifference(
+ decodedRgba(file, width, height),
+ decodedRgba(parallel[index]!, width, height),
+ ));
+ // Chromium may raster the same identity-transformed antialiased glyph edge
+ // through two equivalent compositor paths in separate browser processes.
+ // The exact partition witness above deliberately avoids that path. This
+ // complete Box/selector matrix instead permits only a microscopic edge
+ // delta while still rejecting any changed layout, unit state or region.
+ assert.ok(partitionDifferences.every((difference) => difference.pixels <= 64 && difference.total <= 3_000),
+ `Text Box/sequence output changed under partitioned rendering: ${JSON.stringify(partitionDifferences)}`);
+ const first = decodedRgba(sequential[0]!, width, height);
+ const middle = decodedRgba(sequential[8]!, width, height);
+ const last = decodedRgba(sequential.at(-1)!, width, height);
+ const visible = (rgba: Buffer) => matchingPixels(rgba, width, { left: 0, top: 0, right: width, bottom: height }, (r, g, b) => r + g + b > 160);
+ const visibility = { first: visible(first), middle: visible(middle), last: visible(last) };
+ assert.ok(visibility.middle > visibility.first,
+ `Text sequence enter and loop states did not become visible: ${JSON.stringify(visibility)}`);
+ assert.ok(visibility.last > visibility.first,
+ `Text sequence completion did not retain its final state: ${JSON.stringify(visibility)}`);
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 0, right: width, bottom: height }, (r, g, b) => b > 100 && r < 100) > 250,
+ "isolated word Box Paint did not paint");
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 0, right: width, bottom: height }, (r, g, b) => g > 70 && r < 100) > 500,
+ "content/joined word Box Paint did not paint");
+ assert.ok(matchingPixels(middle, width, { left: 0, top: 0, right: width, bottom: height }, (r, g, b) => r > 120 && g > 70 && b < 80) > 150,
+ "line/grapheme Box Paint did not paint");
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
+test("vertical Text paints in its authored direction and bounded shrink fails closed", {
+ skip: !enabled,
+ timeout: 120_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-text-vertical-shrink-"));
+ try {
+ const width = 320;
+ const height = 320;
+ const fps = 12;
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: 1 / fps,
+ frameRate: { numerator: fps, denominator: 1 },
+ });
+ const installed = await installedOpenFont("noto-sans-sc", 700, "normal");
+ const font = installed.font;
+ const paths = new Map<Digest, string>();
+ let fontIndex = 0;
+ for (const [artifactDigest, bytes] of installed.bytes) {
+ const name = `font-${fontIndex++}.woff2`;
+ await writeFile(path.join(temp, name), bytes);
+ paths.set(artifactDigest, `./${name}`);
+ }
+ const style = (id: string, writingMode: "horizontal-tb" | "vertical-rl", overflow: "visible" | "shrink", minimumScale?: number): TextStyle => sealTextStyle({
+ contract: "svml.text-style@1", id, stackingOrder: 10,
+ typography: {
+ fonts: [font], sizePx: 56, weight: 700, style: "normal", axes: [], features: [],
+ synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+ lineHeight: 1, language: "zh-Hans", direction: "auto", writingMode,
+ baselineShiftPx: 0, tabSize: 4, indentationPx: 0, paragraphBeforePx: 0,
+ paragraphAfterPx: 0, transform: "none", variantCaps: "normal", verticalAlign: "baseline",
+ decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }],
+ area: {
+ inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "center", blockAlign: "center", wrap: "word", overflow,
+ ...(minimumScale === undefined ? {} : { maxLines: 1, minimumScale }),
+ clipToFrame: true, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ point: { anchorInline: "center", anchorBlock: "center" },
+ path: { side: "left", orientation: "follow", startMarginPx: 0, endMarginPx: 0, align: "start", reverse: false, overflow: "visible" },
+ });
+ const compile = (id: string, text: string, frame: { xPx: number; yPx: number; widthPx: number; heightPx: number }, textStyle: TextStyle) => compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id,
+ canvas: { width, height, clearColor: "#000000" },
+ tracks: [renderTextTrack(space, sealTextTrackProgram({
+ contract: "svml.text-track-program@1", id,
+ items: [{
+ id, sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: 1 }, tieBreak: id,
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", ...frame } },
+ document: { paragraphs: [{ id: `${id}-p`, inlines: [{ kind: "text", id: `${id}-r`, text }] }] },
+ style: textStyle, motion: stillTextMotion(),
+ }],
+ }))],
+ }), space);
+ const materialize = (document: ReturnType<typeof compileHyperframesDocument>) => materializeHyperframesHtml(document, (artifact) => {
+ const materialized = paths.get(artifact.digest);
+ if (materialized === undefined) throw new Error(`Unexpected vertical Text Artifact ${artifact.digest}`);
+ return materialized;
+ });
+
+ await writeFile(path.join(temp, "index.html"), materialize(compile(
+ "vertical", "垂直文字AB", { xPx: 20, yPx: 20, widthPx: 280, heightPx: 280 },
+ style("vertical-style", "vertical-rl", "visible"),
+ )));
+ const verticalOutput = path.join(temp, "vertical-output");
+ await mkdir(verticalOutput);
+ const verticalResult = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", verticalOutput, "--fps", String(fps), "--workers", "1",
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 100_000 });
+ assert.equal(verticalResult.status, 0, `${verticalResult.stdout}\n${verticalResult.stderr}`);
+ const verticalFrames = await collectPngs(verticalOutput);
+ assert.equal(verticalFrames.length, 1);
+ const verticalRgba = decodedRgba(verticalFrames[0]!, width, height);
+ const bounds = matchingBounds(verticalRgba, width, { left: 0, top: 0, right: width, bottom: height }, (r, g, b) => r + g + b > 300);
+ assert(bounds !== undefined);
+ assert.ok(bounds.bottom - bounds.top > (bounds.right - bounds.left) * 1.8,
+ `vertical writing did not produce a vertical ink column: ${JSON.stringify(bounds)}`);
+
+ await writeFile(path.join(temp, "index.html"), materialize(compile(
+ "impossible-shrink", "THIS AUTHORED TEXT CANNOT FIT", { xPx: 120, yPx: 140, widthPx: 80, heightPx: 30 },
+ style("impossible-shrink-style", "horizontal-tb", "shrink", 0.9),
+ )));
+ const shrinkOutput = path.join(temp, "shrink-output");
+ await mkdir(shrinkOutput);
+ const shrinkResult = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", shrinkOutput, "--fps", String(fps), "--workers", "1",
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 100_000 });
+ assert.notEqual(shrinkResult.status, 0, "bounded Text shrink silently rendered below its authored minimum");
+ assert.match(`${shrinkResult.stdout}\n${shrinkResult.stderr}`, /Text cannot fit at its authored minimum scale/u);
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
test("Media two-frame sampling, alpha, local motion and handoff survive partitioned browser rendering", {
skip: !enabled,
timeout: 120_000,
@@ -798,6 +1417,572 @@ test("Media two-frame sampling, alpha, local motion and handoff survive partitio
}
});
+test("DepthStack Deck reflow, exact labels and old-system layout survive partitioned browser rendering", {
+ skip: !enabled,
+ timeout: 120_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-depth-stack-visual-"));
+ try {
+ const width = 240;
+ const height = 180;
+ const fps = 12;
+ const frames = 18;
+ const installed = await installedOpenFont("inter", 700, "normal");
+ const font = installed.font;
+ const colors = [
+ { id: "claim", rgba: [240, 45, 55, 255] as const },
+ { id: "proof", rgba: [25, 220, 85, 255] as const },
+ { id: "result", rgba: [35, 90, 245, 255] as const },
+ ];
+ const paths = new Map<Digest, string>();
+ const artifacts = colors.map(({ id, rgba }) => {
+ const bytes = rgbaPng(120, 90, rgba);
+ const artifact: BlobRef = {
+ kind: "blob", digest: digest(bytes), size: bytes.byteLength, mediaType: "image/png",
+ };
+ paths.set(artifact.digest, `./${id}.png`);
+ return { id, bytes, artifact };
+ });
+ for (const value of artifacts) await writeFile(path.join(temp, `${value.id}.png`), value.bytes);
+ let fontIndex = 0;
+ for (const [artifactDigest, bytes] of installed.bytes) {
+ const name = `font-${fontIndex++}.woff2`;
+ await writeFile(path.join(temp, name), bytes);
+ paths.set(artifactDigest, `./${name}`);
+ }
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: frames / fps,
+ frameRate: { numerator: fps, denominator: 1 },
+ });
+ const canvas = sealCanvasSpace({
+ contract: "svml.canvas-space@1", widthPx: width, heightPx: height,
+ origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+ });
+ const fit = {
+ contract: "svml.content-fit@1" as const, sizing: "cover" as const,
+ framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 }, constraint: "bounded" as const,
+ };
+ const label = (id: string): DepthStackCardLabel => deckTrack.sealDepthStackCardLabel({
+ contract: "svml.depth-stack-card-label@1", kind: "text",
+ document: { paragraphs: [{ id: `${id}-p`, inlines: [{ id: `${id}-text`, kind: "text", text: id.toUpperCase() }] }] },
+ typography: {
+ fonts: [font], sizePx: 16, weight: 700, style: "normal", axes: [], features: [], synthesis: "none",
+ kerning: "normal", trackingPx: 0, wordSpacingPx: 0, lineHeight: 1.1, direction: "auto",
+ writingMode: "horizontal-tb", baselineShiftPx: 0, tabSize: 4, indentationPx: 0,
+ paragraphBeforePx: 0, paragraphAfterPx: 0, transform: "none", variantCaps: "normal",
+ verticalAlign: "baseline", decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [
+ {
+ kind: "shadow", paint: { kind: "solid", color: "#000000cc" },
+ offsetX: 0, offsetY: 1, blurPx: 2, spreadPx: 0,
+ },
+ { kind: "fill", paint: { kind: "solid", color: "#ffffff" } },
+ ],
+ flow: {
+ form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 8, inlineEnd: 8, blockStart: 8, blockEnd: 8 },
+ inlineAlign: "center", blockAlign: "end", wrap: "none", overflow: "clip",
+ clipToFrame: true, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ });
+ let cards = deckTrack.createDepthStackCardSet();
+ for (const [index, value] of artifacts.entries()) {
+ let material = mediaTrack.createMediaLayerSet();
+ material = mediaTrack.appendStillMediaLayer(
+ material,
+ value.artifact,
+ { contract: "svml.intrinsic-extent@1", widthPx: 120, heightPx: 90 },
+ fit,
+ mediaTrack.sealMediaSampleLayerSpec({
+ contract: "svml.media-sample-layer-spec@1", id: `${value.id}-material`,
+ appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
+ }),
+ );
+ cards = deckTrack.appendDepthStackCard(
+ cards,
+ material,
+ label(value.id),
+ deckTrack.sealDepthStackCardSpec({
+ contract: "svml.depth-stack-card-spec@1", id: value.id,
+ playback: { future: "hold-head", past: "hold-tail" },
+ }),
+ index * 6,
+ );
+ }
+ const spec = deckTrack.sealDepthStackSpec({
+ contract: "svml.depth-stack-spec@1",
+ visibility: { previous: 1, next: 1, wrap: false },
+ poses: {
+ current: {
+ xPx: 0, yPx: 0, scale: 1, rotationDeg: 0, opacity: 1, stacking: 0,
+ tone: { brightness: 1, contrast: 1, saturation: 1 },
+ },
+ previous: {
+ xPerDepthPx: -25, yPerDepthPx: 17, scalePerDepth: 0.88, rotationPerDepthDeg: -5,
+ rotationMode: "alternate", opacityPerDepth: 0.78, stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.78, contrast: 1, saturation: 0.7 },
+ },
+ next: {
+ xPerDepthPx: 25, yPerDepthPx: -17, scalePerDepth: 0.88, rotationPerDepthDeg: 5,
+ rotationMode: "alternate", opacityPerDepth: 0.78, stackingPerDepth: -1,
+ tonePerDepth: { brightness: 0.78, contrast: 1, saturation: 0.7 },
+ },
+ },
+ reflow: { durationFrames: 3, easing: "ease-in-out" },
+ presentation: {
+ clip: { kind: "rounded", radiusPx: 10 },
+ padding: { topPx: 4, rightPx: 4, bottomPx: 4, leftPx: 4 },
+ border: { widthPx: 2, style: "solid", color: "#ffffff" },
+ shadows: [{ offsetX: 0, offsetY: 5, blurPx: 10, spreadPx: 0, color: "#00000099" }],
+ },
+ motion: {
+ enter: { operator: "fade", durationFrames: 2, easing: "ease-out" },
+ sustain: [],
+ exit: { operator: "fade", durationFrames: 2, easing: "ease-in" },
+ },
+ stackingOrder: 20,
+ });
+ const program = deckTrack.finalizeDepthStack(
+ cards,
+ deckTrack.sealDepthStackHeader({ contract: "svml.depth-stack-header@1", id: "proof-stack" }),
+ { contract: "svml.spatial-frame@1", xPx: 60, yPx: 45, widthPx: 120, heightPx: 90 },
+ spec,
+ frames,
+ space,
+ );
+ const track = deckTrack.renderDepthStack(canvas, space, program);
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "depth-stack-browser-proof",
+ canvas: { width, height, clearColor: "#090b12" }, tracks: [track],
+ }), space);
+ await writeFile(path.join(temp, "index.html"), materializeHyperframesHtml(document, (artifact) => {
+ const materialized = paths.get(artifact.digest);
+ if (materialized === undefined) throw new Error(`Unexpected DepthStack Artifact ${artifact.digest}`);
+ return materialized;
+ }));
+ const render = async (workers: number, name: string): Promise<Buffer[]> => {
+ const output = path.join(temp, name);
+ await mkdir(output);
+ const result = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", String(fps), "--workers", String(workers),
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 110_000 });
+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+ return Promise.all((await collectPngs(output)).map(async (file) => decodedRgba(file, width, height)));
+ };
+ const sequential = await render(1, "sequential");
+ const partitioned = await render(3, "partitioned");
+ assert.equal(sequential.length, frames);
+ assert.equal(partitioned.length, frames);
+ for (let frameIndex = 0; frameIndex < frames; frameIndex += 1) {
+ assert.deepEqual(partitioned[frameIndex], sequential[frameIndex],
+ `DepthStack frame ${frameIndex} changed under partitioned/out-of-order evaluation`);
+ }
+ const currentColorCount = (frame: Buffer, color: "red" | "green" | "blue") => matchingPixels(
+ frame, width, { left: 35, top: 20, right: 205, bottom: 160 },
+ (red, green, blue) => color === "red"
+ ? red > 170 && green < 100 && blue < 110
+ : color === "green"
+ ? green > 150 && red < 100 && blue < 130
+ : blue > 160 && red < 120 && green < 150,
+ );
+ assert.ok(currentColorCount(sequential[3]!, "red") > 4_000, "first Deck stage did not paint its current Card");
+ assert.ok(currentColorCount(sequential[9]!, "green") > 4_000, "second Deck stage did not reflow to its current Card");
+ assert.ok(currentColorCount(sequential[15]!, "blue") > 4_000, "third Deck stage did not reflow to its current Card");
+ assert.notDeepEqual(sequential[5], sequential[7], "Deck reflow produced no visual state change");
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
+test("all four Ranking components paint frame-pure progressive states under partitioned browser rendering", {
+ skip: !enabled,
+ timeout: 120_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-ranking-visual-"));
+ try {
+ const width = 480;
+ const height = 720;
+ const fps = 12;
+ const frames = 24;
+ const installed = await installedOpenFont("inter", 700, "normal");
+ const font = installed.font;
+ const paths = new Map<Digest, string>();
+ let fontIndex = 0;
+ for (const [artifactDigest, bytes] of installed.bytes) {
+ const name = `font-${fontIndex++}.woff2`;
+ await writeFile(path.join(temp, name), bytes);
+ paths.set(artifactDigest, `./${name}`);
+ }
+ const colors = [
+ [238, 54, 67, 255],
+ [34, 197, 94, 255],
+ [55, 105, 245, 255],
+ ] as const;
+ const icons = colors.map((rgba, index) => {
+ const bytes = rgbaPng(40, 40, rgba);
+ const artifact: BlobRef = { kind: "blob", digest: digest(bytes), size: bytes.byteLength, mediaType: "image/png" };
+ const name = `ranking-${index + 1}.png`;
+ paths.set(artifact.digest, `./${name}`);
+ return { bytes, artifact, name };
+ });
+ for (const icon of icons) await writeFile(path.join(temp, icon.name), icon.bytes);
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: frames / fps,
+ frameRate: { numerator: fps, denominator: 1 },
+ });
+ const map = {
+ contract: "svml.complete-semantic-map@1" as const,
+ tokens: [],
+ anchors: [
+ { identity: "outer-start", timeSec: 0, frame: 0 },
+ { identity: "rank-1", timeSec: 2 / fps, frame: 2 },
+ { identity: "rank-2", timeSec: 8 / fps, frame: 8 },
+ { identity: "rank-3", timeSec: 14 / fps, frame: 14 },
+ { identity: "terminal", timeSec: 20 / fps, frame: 20 },
+ { identity: "outer-end", timeSec: frames / fps, frame: frames },
+ ],
+ };
+ const outer = {
+ contract: "svml.narrative-selection@1" as const, id: "ranking-window",
+ occurrences: [{ occurrence: 0, startAnchorId: "outer-start", endAnchorId: "outer-end" }],
+ };
+ const triggers = {
+ contract: "svml.narrative-moment@1" as const, id: "ranking-next",
+ occurrences: ["rank-1", "rank-2", "rank-3"].map((anchorId, occurrence) => ({ occurrence, anchorId })),
+ };
+ const terminal = {
+ contract: "svml.narrative-moment@1" as const, id: "ranking-terminal",
+ occurrences: [{ occurrence: 0, anchorId: "terminal" }],
+ };
+ const schedule = (header: rankingTrack.RankingHeader, specs: readonly rankingTrack.RankingItemSpec[]) => {
+ let set = rankingTrack.createRankingItemSpecSet(header);
+ for (const spec of specs) set = rankingTrack.appendRankingItemSpec(set, spec);
+ return rankingTrack.buildRankingSchedule({ header, items: set, map, space, outer, triggers, terminal });
+ };
+ const recipe = (path: string, properties: SvsRecipe["properties"]): SvsRecipe => ({
+ contract: "svml.svs-recipe@1", path, properties,
+ });
+ const tierHeader = rankingTrack.sealRankingHeader({ contract: "svml.ranking-header@1", id: "browser-tier", variant: "tier-board" });
+ const tierSpecs = [
+ { contract: "svml.tier-board-item-spec@1", variant: "tier-board", id: "tier-one", tier: "s", entry: "stage" },
+ { contract: "svml.tier-board-item-spec@1", variant: "tier-board", id: "tier-two", tier: "a", entry: "direct" },
+ { contract: "svml.tier-board-item-spec@1", variant: "tier-board", id: "tier-three", tier: "s", entry: "direct" },
+ ] as const;
+ let tierItems = rankingTrack.createTierBoardItemSet();
+ tierSpecs.forEach((spec, index) => { tierItems = rankingTrack.appendTierBoardItem(tierItems, spec, icons[index]!.artifact); });
+ const tierStyle = rankingTrack.decodeTierBoardStyle(recipe("browser.tier", {
+ rows: "s:S:#ef4444|a:A:#22c55e", "font-size": 15, "appear-frames": 2, "move-frames": 2,
+ padding: 6, "label-width": 36, "row-height": 54, "row-gap": 4, "cell-gap": 5,
+ "icon-size": 42, "icon-radius": 7, "stage-size": 56,
+ }), font).style;
+ const tierTrack = rankingTrack.renderTierBoard(space, rankingTrack.buildTierBoardProgram(
+ tierHeader, { contract: "svml.spatial-frame@1", xPx: 20, yPx: 20, widthPx: 440, heightPx: 140 },
+ schedule(tierHeader, tierSpecs), tierStyle, tierItems,
+ ));
+
+ const columnHeader = rankingTrack.sealRankingHeader({ contract: "svml.ranking-header@1", id: "browser-column", variant: "column" });
+ const columnSpecs = ["one", "two", "three"].map((id, index) => ({
+ contract: "svml.column-item-spec@1" as const, variant: "column" as const, id: `column-${id}`, label: `${index + 1}. ${id}`,
+ }));
+ let columnItems = rankingTrack.createColumnItemSet();
+ columnSpecs.forEach((spec, index) => { columnItems = rankingTrack.appendColumnItem(columnItems, spec, index === 1 ? icons[index]!.artifact : undefined); });
+ const columnStyle = rankingTrack.decodeColumnStyle(recipe("browser.column", {
+ "font-size": 15, "appear-frames": 2, "move-frames": 2, padding: 6, "row-height": 35,
+ "row-gap": 4, "icon-size": 26, "icon-radius": 5, "stage-size": 46,
+ }), font).style;
+ const columnTrack = rankingTrack.renderColumn(space, rankingTrack.buildColumnProgram(
+ columnHeader, { contract: "svml.spatial-frame@1", xPx: 20, yPx: 180, widthPx: 440, heightPx: 140 },
+ schedule(columnHeader, columnSpecs), columnStyle, columnItems,
+ ));
+
+ const topHeader = rankingTrack.sealRankingHeader({ contract: "svml.ranking-header@1", id: "browser-top", variant: "top-three" });
+ const topSpecs = ["Gold", "Silver", "Bronze"].map((label, index) => ({
+ contract: "svml.top-three-item-spec@1" as const, variant: "top-three" as const, id: `top-${index + 1}`, label,
+ }));
+ let topItems = rankingTrack.createTopThreeItemSet();
+ topSpecs.forEach((spec, index) => { topItems = rankingTrack.appendTopThreeItem(topItems, spec, index === 1 ? undefined : icons[index]!.artifact); });
+ const topStyle = rankingTrack.decodeTopThreeStyle(recipe("browser.top", {
+ "font-size": 15, "appear-frames": 2, "move-frames": 2, "icon-size": 54, "icon-radius": 27,
+ "slot-gap": 30, "ring-width": 3, "label-gap": 5, "baseline-y": 0.45,
+ }), font).style;
+ const topTrack = rankingTrack.renderTopThree(space, rankingTrack.buildTopThreeProgram(
+ topHeader, { contract: "svml.spatial-frame@1", xPx: 20, yPx: 340, widthPx: 440, heightPx: 140 },
+ schedule(topHeader, topSpecs), topStyle, topItems,
+ ));
+
+ const typeHeader = rankingTrack.sealRankingHeader({ contract: "svml.ranking-header@1", id: "browser-typewriter", variant: "typewriter-list" });
+ const typeSpecs = [
+ { contract: "svml.typewriter-item-spec@1", variant: "typewriter-list", id: "typed-one", text: "Fast", winner: false },
+ { contract: "svml.typewriter-item-spec@1", variant: "typewriter-list", id: "typed-two", text: "Clear", winner: false, emphasis: { start: 0, endExclusive: 2 } },
+ { contract: "svml.typewriter-item-spec@1", variant: "typewriter-list", id: "typed-three", text: "Best", winner: true },
+ ] as const;
+ let typeItems = rankingTrack.createTypewriterItemSet();
+ typeSpecs.forEach((spec) => { typeItems = rankingTrack.appendTypewriterItem(typeItems, spec); });
+ const typeStyle = rankingTrack.decodeTypewriterListStyle(recipe("browser.typewriter", {
+ "title-font-size": 20, "item-font-size": 16, "appear-frames": 2, "move-frames": 2,
+ padding: 12, "row-gap": 4, "title-gap": 5, "frames-per-grapheme": 1, "winner-frames": 1,
+ }), font).style;
+ const typeTrack = rankingTrack.renderTypewriterList(space, rankingTrack.buildTypewriterListProgram(
+ typeHeader, "RANKING", { contract: "svml.spatial-frame@1", xPx: 20, yPx: 500, widthPx: 440, heightPx: 195 },
+ schedule(typeHeader, typeSpecs), typeStyle, typeItems,
+ ));
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "ranking-browser-proof",
+ canvas: { width, height, clearColor: "#090b12" },
+ tracks: [tierTrack, columnTrack, topTrack, typeTrack],
+ }), space);
+ await writeFile(path.join(temp, "index.html"), materializeHyperframesHtml(document, (artifact) => {
+ const materialized = paths.get(artifact.digest);
+ if (materialized === undefined) throw new Error(`Unexpected Ranking Artifact ${artifact.digest}`);
+ return materialized;
+ }));
+ const render = async (workers: number, name: string): Promise<Buffer[]> => {
+ const output = path.join(temp, name);
+ await mkdir(output);
+ const result = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", String(fps), "--workers", String(workers),
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 110_000 });
+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+ return Promise.all((await collectPngs(output)).map(async (file) => decodedRgba(file, width, height)));
+ };
+ const sequential = await render(1, "sequential");
+ const partitioned = await render(3, "partitioned");
+ assert.equal(sequential.length, frames);
+ assert.equal(partitioned.length, frames);
+ for (let frameIndex = 0; frameIndex < frames; frameIndex += 1) {
+ const left = partitioned[frameIndex]!;
+ const right = sequential[frameIndex]!;
+ if (Buffer.compare(left, right) !== 0) {
+ let minX = width;
+ let minY = height;
+ let maxX = -1;
+ let maxY = -1;
+ let count = 0;
+ let maxChannelDelta = 0;
+ let totalChannelDelta = 0;
+ for (let offset = 0; offset < left.length; offset += 4) {
+ if (left[offset] === right[offset] && left[offset + 1] === right[offset + 1]
+ && left[offset + 2] === right[offset + 2] && left[offset + 3] === right[offset + 3]) continue;
+ const pixel = offset / 4;
+ const x = pixel % width;
+ const y = Math.floor(pixel / width);
+ minX = Math.min(minX, x); maxX = Math.max(maxX, x);
+ minY = Math.min(minY, y); maxY = Math.max(maxY, y);
+ for (let channel = 0; channel < 4; channel += 1) {
+ const delta = Math.abs(left[offset + channel]! - right[offset + channel]!);
+ maxChannelDelta = Math.max(maxChannelDelta, delta);
+ totalChannelDelta += delta;
+ }
+ count += 1;
+ }
+ // Chromium can raster the same identity-transformed glyph/icon edge
+ // through equivalent compositor paths in separate worker processes.
+ // Bound that microscopic edge noise tightly while continuing to reject
+ // any changed Ranking state, geometry or painted region.
+ assert.ok(count <= 512 && maxChannelDelta <= 48 && totalChannelDelta <= 2_500,
+ `Ranking frame ${frameIndex} changed at ${count} pixels (max channel delta ${maxChannelDelta}, total ${totalChannelDelta}) in [${minX},${minY}]–[${maxX},${maxY}] under partitioning`);
+ }
+ }
+ assert.notDeepEqual(sequential[3], sequential[9], "Ranking stages produced no visual state change");
+ assert.notDeepEqual(sequential[9], sequential[15], "later Ranking triggers produced no visual state change");
+ const settled = sequential[22]!;
+ for (const [name, top, bottom] of [["TierBoard", 20, 160], ["Column", 180, 320], ["TopThree", 340, 480], ["TypewriterList", 500, 695]] as const) {
+ assert.ok(matchingPixels(settled, width, { left: 20, top, right: 460, bottom }, (red, green, blue) => red + green + blue > 120) > 500,
+ `${name} did not paint its settled suffix`);
+ }
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
+test("all Spatial fit modes and equal-point alignments reach exact browser pixels", {
+ skip: !enabled,
+ timeout: 120_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-spatial-visual-"));
+ try {
+ const width = 530;
+ const height = 280;
+ const sourceBytes = rgbaPng(40, 20, [250, 205, 25, 255]);
+ const source: BlobRef = {
+ kind: "blob", digest: digest(sourceBytes), size: sourceBytes.byteLength, mediaType: "image/png",
+ };
+ await writeFile(path.join(temp, "source.png"), sourceBytes);
+ const canvas = sealCanvasSpace({
+ contract: "svml.canvas-space@1", widthPx: width, heightPx: height,
+ origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+ });
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1", durationSec: 1, frameRate: { numerator: 1, denominator: 1 },
+ });
+ const header = mediaTrack.sealMediaTrackHeader({ contract: "svml.media-track-header@1", id: "spatial-browser" });
+ const extent = { contract: "svml.intrinsic-extent@1" as const, widthPx: 40, heightPx: 20 };
+ const appearance = { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } };
+ let set = mediaTrack.createMediaTrackSet();
+ let stackingOrder = 1;
+ const append = (
+ id: string,
+ frame: { readonly contract: "svml.spatial-frame@1"; readonly xPx: number; readonly yPx: number; readonly widthPx: number; readonly heightPx: number },
+ fit: {
+ readonly contract: "svml.content-fit@1";
+ readonly sizing: "contain" | "cover" | "fit-width" | "fit-height" | "native" | "scale-down" | "stretch";
+ readonly framePoint: { readonly x: number; readonly y: number };
+ readonly contentPoint: { readonly x: number; readonly y: number };
+ readonly offsetPx: { readonly x: number; readonly y: number };
+ readonly constraint: "bounded" | "free";
+ },
+ clip: "frame" | "none" = "frame",
+ ): void => {
+ const layers = mediaTrack.appendStillMediaLayer(
+ mediaTrack.createMediaLayerSet(), source, extent, fit,
+ mediaTrack.sealMediaSampleLayerSpec({
+ contract: "svml.media-sample-layer-spec@1", id: `${id}:source`, appearance,
+ }),
+ );
+ set = mediaTrack.appendProgramMediaItem(
+ set, header, space, canvas, layers, frame,
+ mediaTrack.sealMediaItemSpec({
+ contract: "svml.media-item-spec@1", id,
+ projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ expansion: { kind: "one" },
+ presentation: {
+ clip: { kind: clip },
+ padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 },
+ shadows: [],
+ },
+ motion: { sustain: [] }, stackingOrder: stackingOrder++,
+ }),
+ mediaTrack.createMediaSoundSet(),
+ );
+ };
+
+ const sizings = ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] as const;
+ for (const [index, sizing] of sizings.entries()) {
+ append(`fit-${sizing}`, {
+ contract: "svml.spatial-frame@1", xPx: 5 + index * 75, yPx: 5, widthPx: 60, heightPx: 60,
+ }, {
+ contract: "svml.content-fit@1", sizing,
+ framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 }, constraint: "bounded",
+ });
+ }
+ const points = [0, 0.5, 1] as const;
+ for (const [row, y] of points.entries()) {
+ for (const [column, x] of points.entries()) {
+ append(`align-${column}-${row}`, {
+ contract: "svml.spatial-frame@1", xPx: 5 + column * 70, yPx: 85 + row * 50, widthPx: 50, heightPx: 40,
+ }, {
+ contract: "svml.content-fit@1", sizing: "native",
+ framePoint: { x, y }, contentPoint: { x, y }, offsetPx: { x: 0, y: 0 }, constraint: "bounded",
+ });
+ }
+ }
+ const displacedFit = {
+ contract: "svml.content-fit@1" as const, sizing: "native" as const,
+ framePoint: { x: 1, y: 1 }, contentPoint: { x: 0, y: 0 },
+ offsetPx: { x: 20, y: 20 },
+ };
+ append("bounded-displaced", {
+ contract: "svml.spatial-frame@1", xPx: 230, yPx: 85, widthPx: 50, heightPx: 40,
+ }, { ...displacedFit, constraint: "bounded" });
+ append("free-displaced", {
+ contract: "svml.spatial-frame@1", xPx: 300, yPx: 85, widthPx: 50, heightPx: 40,
+ }, { ...displacedFit, constraint: "free" }, "none");
+ const stretch = {
+ contract: "svml.content-fit@1" as const, sizing: "stretch" as const,
+ framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 }, constraint: "bounded" as const,
+ };
+ append("partially-off-canvas", {
+ contract: "svml.spatial-frame@1", xPx: -20, yPx: 235, widthPx: 40, heightPx: 40,
+ }, stretch);
+ append("fully-off-canvas", {
+ contract: "svml.spatial-frame@1", xPx: -80, yPx: 235, widthPx: 40, heightPx: 40,
+ }, stretch);
+
+ const track = mediaTrack.projectMediaVisualTrack(space, mediaTrack.finalizeMediaTrack(set, header, space));
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "spatial-browser-proof",
+ canvas: { width, height, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ await writeFile(path.join(temp, "index.html"), materializeHyperframesHtml(document, (artifact) => {
+ if (artifact.digest !== source.digest) throw new Error(`Unexpected Spatial Artifact ${artifact.digest}`);
+ return "./source.png";
+ }));
+ const output = path.join(temp, "frames");
+ await mkdir(output);
+ const result = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", "1", "--workers", "1",
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 110_000 });
+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+ const files = await collectPngs(output);
+ assert.equal(files.length, 1);
+ const rgba = decodedRgba(files[0]!, width, height);
+ const yellow = (red: number, green: number, blue: number): boolean => red > 220 && green > 170 && blue < 80;
+ const fitBounds = [
+ { left: 0, top: 15, right: 60, bottom: 45 },
+ { left: 0, top: 0, right: 60, bottom: 60 },
+ { left: 0, top: 15, right: 60, bottom: 45 },
+ { left: 0, top: 0, right: 60, bottom: 60 },
+ { left: 10, top: 20, right: 50, bottom: 40 },
+ { left: 10, top: 20, right: 50, bottom: 40 },
+ { left: 0, top: 0, right: 60, bottom: 60 },
+ ];
+ for (const [index, expected] of fitBounds.entries()) {
+ const frameLeft = 5 + index * 75;
+ assert.deepEqual(
+ matchingBounds(rgba, width, { left: frameLeft, top: 5, right: frameLeft + 60, bottom: 65 }, yellow),
+ {
+ left: frameLeft + expected.left, top: 5 + expected.top,
+ right: frameLeft + expected.right, bottom: 5 + expected.bottom,
+ },
+ sizings[index],
+ );
+ }
+ for (const [row, y] of points.entries()) {
+ for (const [column, x] of points.entries()) {
+ const frameLeft = 5 + column * 70;
+ const frameTop = 85 + row * 50;
+ assert.deepEqual(
+ matchingBounds(rgba, width, {
+ left: frameLeft, top: frameTop, right: frameLeft + 50, bottom: frameTop + 40,
+ }, yellow),
+ {
+ left: frameLeft + 10 * x, top: frameTop + 20 * y,
+ right: frameLeft + 10 * x + 40, bottom: frameTop + 20 * y + 20,
+ },
+ `equal-point ${x},${y}`,
+ );
+ }
+ }
+ assert.deepEqual(
+ matchingBounds(rgba, width, { left: 220, top: 80, right: 290, bottom: 135 }, yellow),
+ { left: 240, top: 105, right: 280, bottom: 125 },
+ "bounded unequal focal points",
+ );
+ assert.deepEqual(
+ matchingBounds(rgba, width, { left: 350, top: 130, right: 430, bottom: 180 }, yellow),
+ { left: 370, top: 145, right: 410, bottom: 165 },
+ "free unequal focal points",
+ );
+ assert.deepEqual(
+ matchingBounds(rgba, width, { left: 0, top: 235, right: 60, bottom: 275 }, yellow),
+ { left: 0, top: 235, right: 20, bottom: 275 },
+ "partially and fully off-Canvas Frames",
+ );
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
+
test("every official Screen Overlay survives real sequential and parallel browser frames identically", {
skip: !enabled,
timeout: 120_000,
diff --git a/packages/hyperframes/test/track-expressiveness.test.ts b/packages/hyperframes/test/track-expressiveness.test.ts
index a600af17..f0e1f7e2 100644
--- a/packages/hyperframes/test/track-expressiveness.test.ts
+++ b/packages/hyperframes/test/track-expressiveness.test.ts
@@ -1,7 +1,9 @@
-import type { CompositableSurfaceRef } from "@narratage/media";
-import { sealProgramSpace } from "@narratage/program-space";
-import { sealComposition, sealVisualTrack } from "@narratage/composition";
+import { mediaDependency, mediaTypes } from "@narratage/media";
+import type { CompositableSurfaceRef, FontArtifactRef } from "@narratage/media";
+import { programSpaceDependency, programSpaceTypes, sealProgramSpace } from "@narratage/program-space";
+import { compositionDependency, compositionTypes, sealComposition, sealVisualTrack } from "@narratage/composition";
import type { Track, VisualElement, VisualPresent, VisualTrack } from "@narratage/composition";
+import { createResolvedClosure } from "@narratage/core";
import assert from "node:assert/strict";
import test from "node:test";
@@ -10,7 +12,9 @@ import {
compileHyperframesDocument,
} from "@narratage/hyperframes";
import { digestOf } from "@narratage/protocol";
-import type { BlobRef } from "@narratage/protocol";
+import type { BlobRef, ModuleManifest } from "@narratage/protocol";
+import * as rankingTrack from "@narratage/ranking";
+import { videoContractManifests } from "../../test-support/video-domain.js";
const programSpace = sealProgramSpace({
contract: "svml.program-space@1",
@@ -324,31 +328,37 @@ test("one content box lowers independent backdrop and foreground samples of one
});
test("Presents from one authoring Track interleave with a peer Track by absolute stacking", () => {
- const ranking = sealVisualTrack({
- contract: "svml.visual-track@1",
- visualIr: "svml.visual-ir@1",
- id: "ranking-witness",
- presents: [
- {
- id: "board",
- span: { startFrame: 0, endFrameExclusive: 300 },
- stacking: { order: 30, tieBreak: "board" },
- elements: [{ id: "board", order: 0, kind: "box", style: [{ name: "background-color", value: "#ffffff" }] }],
- },
- {
- id: "icon-1",
- span: { startFrame: 30, endFrameExclusive: 300 },
- stacking: { order: 80, tieBreak: "icon-1" },
- elements: [{ id: "icon", order: 0, kind: "text", text: "★", style: [{ name: "font-size", value: "72px" }] }],
- },
- {
- id: "icon-2",
- span: { startFrame: 60, endFrameExclusive: 300 },
- stacking: { order: 90, tieBreak: "icon-2" },
- elements: [{ id: "icon", order: 0, kind: "text", text: "◆", style: [{ name: "font-size", value: "72px" }] }],
- },
- ],
- });
+ const header = rankingTrack.sealRankingHeader({ contract: "svml.ranking-header@1", id: "ranking-witness", variant: "column" });
+ const first = { contract: "svml.column-item-spec@1", variant: "column", id: "icon-1", label: "One", stackingOrder: 80 } as const;
+ const second = { contract: "svml.column-item-spec@1", variant: "column", id: "icon-2", label: "Two", stackingOrder: 90 } as const;
+ let items = rankingTrack.createColumnItemSet();
+ items = rankingTrack.appendColumnItem(items, first);
+ items = rankingTrack.appendColumnItem(items, second);
+ const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ sources: [{ artifact: { kind: "blob", digest: digestOf("ranking-interleave-font"), size: 32, mediaType: "font/woff2" } }],
+ weight: 700, style: "normal",
+ };
+ const style = rankingTrack.decodeColumnStyle({
+ contract: "svml.svs-recipe@1", path: "ranking.interleave",
+ properties: { "board-stack": 30, "stage-stack": 40, "item-stack": 80 },
+ }, font).style;
+ const ranking = rankingTrack.renderColumn(programSpace, rankingTrack.buildColumnProgram(
+ header,
+ { contract: "svml.spatial-frame@1", xPx: 80, yPx: 180, widthPx: 920, heightPx: 900 },
+ {
+ contract: "svml.ranking-schedule@1", id: "ranking-witness.schedule", variant: "column",
+ outer: { startFrame: 0, endFrameExclusive: 300 }, terminalFrame: 240,
+ entries: [
+ { itemId: "icon-1", triggerOccurrenceId: "next#0", triggerFrame: 30,
+ stage: { startFrame: 30, endFrameExclusive: 90 }, cumulative: { startFrame: 30, endFrameExclusive: 300 }, settled: { startFrame: 90, endFrameExclusive: 300 } },
+ { itemId: "icon-2", triggerOccurrenceId: "next#1", triggerFrame: 90,
+ stage: { startFrame: 90, endFrameExclusive: 240 }, cumulative: { startFrame: 90, endFrameExclusive: 300 }, settled: { startFrame: 240, endFrameExclusive: 300 } },
+ ],
+ },
+ style,
+ items,
+ ));
const peer = sealVisualTrack({
contract: "svml.visual-track@1",
visualIr: "svml.visual-ir@1",
@@ -361,15 +371,41 @@ test("Presents from one authoring Track interleave with a peer Track by absolute
}],
});
const document = compileHyperframesDocument(composition("interleaved-ranking", [ranking, peer]), programSpace);
- const boardAt = document.html.indexOf('data-svml-present-id="board"');
+ const boardAt = document.html.indexOf('data-svml-present-id="ranking-witness:board"');
const peerAt = document.html.indexOf('data-svml-present-id="peer"');
- const icon1At = document.html.indexOf('data-svml-present-id="icon-1"');
- const icon2At = document.html.indexOf('data-svml-present-id="icon-2"');
+ const icon1At = document.html.indexOf('data-svml-present-id="ranking-witness:item:icon-1:stage"');
+ const icon2At = document.html.indexOf('data-svml-present-id="ranking-witness:item:icon-2:stage"');
assert.ok(boardAt < peerAt && peerAt < icon1At && icon1At < icon2At);
assert.doesNotMatch(document.html, /svml-visual-track|isolation:isolate/u);
});
-test("a complex owned visual may materialize as a typed compositable Surface without a component discriminator", () => {
+test("an independently installed non-native Text package crosses only the typed Surface waist", () => {
+ const externalModule = { name: "example.volumetric-text", version: "1" } as const;
+ const externalManifest: ModuleManifest = {
+ format: "svml.module@1",
+ name: externalModule.name,
+ version: externalModule.version,
+ dependencies: [programSpaceDependency, mediaDependency, compositionDependency],
+ types: [],
+ capabilities: [],
+ surfaces: [],
+ producers: [{
+ name: "place-materialized-text",
+ inputs: [
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "surface", type: mediaTypes.compositableSurface },
+ ],
+ outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ needs: [],
+ implementation: {
+ kind: "registered",
+ locator: "example.volumetric-text/place-materialized-text",
+ digest: digestOf("example.volumetric-text/place-materialized-text@1"),
+ },
+ }],
+ };
+ const closure = createResolvedClosure([...videoContractManifests, externalManifest]);
+ assert.ok(closure.modules.some((module) => module.ref.name === externalModule.name));
const materialized: CompositableSurfaceRef = {
contract: "svml.compositable-surface@1",
artifact: {
@@ -412,5 +448,11 @@ test("a complex owned visual may materialize as a typed compositable Surface wit
assert.match(document.html, /data-svml-alpha-mode="straight"/u);
assert.equal("renderer" in track, false);
assert.equal("component" in track, false);
- // The Surface contract, not the WebM extension, now carries the compositing promise.
+ assert.deepEqual(externalManifest.producers[0]?.inputs.map((input) => input.type), [
+ programSpaceTypes.programSpace,
+ mediaTypes.compositableSurface,
+ ]);
+ // The separately installed package owns extrusion/material/light/camera
+ // semantics before this boundary. Public Track and HyperFrames see only the
+ // declared Surface, never an advanced-Text discriminator.
});
diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.ts
index ad7fb27f..54c6ae71 100644
--- a/packages/media-execution/src/execute.ts
+++ b/packages/media-execution/src/execute.ts
@@ -360,6 +360,8 @@ function animatedWebpInspection(source: BlobRef, animation: AnimatedWebp): Media
role: "moving",
width: animation.width,
height: animation.height,
+ sampleAspectRatio: { numerator: 1, denominator: 1 },
+ rotationDegrees: 0,
averageFrameRate: { numerator: numerator / factor, denominator: durationMs / factor },
}],
});
@@ -593,10 +595,14 @@ export async function executeNormalizeMedia(
`fps=fps=${fps}:round=near:start_time=0:eof_action=round`,
`trim=start_frame=0:end_frame=${plan.frameCount}`,
`setpts=N*${need.frameRate.denominator}/(${need.frameRate.numerator}*TB)`,
- "scale=trunc(iw/2)*2:trunc(ih/2)*2",
+ // Autorotation runs before this filter. Expand, never shrink, the axis
+ // carrying non-square samples, then erase SAR so downstream Spatial
+ // receives only truthful square-pixel display dimensions.
+ "scale=trunc(iw*max(sar\\,1)/2)*2:trunc(ih*max(1/sar\\,1)/2)*2",
+ "setsar=1",
].join(",");
const visualInput = animation === undefined
- ? ["-i", input, "-map", `0:${plan.video.index}`]
+ ? ["-autorotate", "-i", input, "-map", `0:${plan.video.index}`]
: ["-f", "concat", "-safe", "0", "-i", await animatedWebpConcat(env, animation, work), "-map", "0:v:0"];
await runProcess({
executable: env.ffmpegPath,
@@ -618,6 +624,9 @@ export async function executeNormalizeMedia(
const visual = inspected.streams.find((item): item is MediaVideoStream => item.kind === "video");
assert(visual?.decodedUnitCount === plan.frameCount && visual.role === "moving",
"Normalized visual frame shape differs from its plan");
+ assert(visual.sampleAspectRatio.numerator === 1 && visual.sampleAspectRatio.denominator === 1
+ && visual.rotationDegrees === 0,
+ "Normalized visual retains non-square samples or display rotation");
const bytes = await readFile(output);
visualArtifact = await env.artifacts.put(bytes, "video/mp4");
visualWidth = visual.width;
diff --git a/packages/media-execution/src/probe.ts b/packages/media-execution/src/probe.ts
index d8fe500b..2747448c 100644
--- a/packages/media-execution/src/probe.ts
+++ b/packages/media-execution/src/probe.ts
@@ -10,6 +10,7 @@ type FfprobeStream = {
readonly codec_name?: unknown;
readonly width?: unknown;
readonly height?: unknown;
+ readonly sample_aspect_ratio?: unknown;
readonly time_base?: unknown;
readonly avg_frame_rate?: unknown;
readonly r_frame_rate?: unknown;
@@ -17,6 +18,8 @@ type FfprobeStream = {
readonly channels?: unknown;
readonly channel_layout?: unknown;
readonly disposition?: { readonly default?: unknown; readonly attached_pic?: unknown };
+ readonly tags?: { readonly rotate?: unknown };
+ readonly side_data_list?: readonly unknown[];
};
type FfprobeFrame = {
@@ -68,6 +71,41 @@ function rational(value: unknown, allowZero = false): MediaRational | undefined
return { numerator, denominator };
}
+function divisor(left: number, right: number): number {
+ let a = Math.abs(left);
+ let b = Math.abs(right);
+ while (b !== 0) [a, b] = [b, a % b];
+ return a;
+}
+
+function sampleAspectRatio(value: unknown): MediaRational {
+ if (typeof value !== "string") return { numerator: 1, denominator: 1 };
+ const match = value.match(/^(\d+):(\d+)$/u);
+ if (match === null) return { numerator: 1, denominator: 1 };
+ const numerator = Number(match[1]);
+ const denominator = Number(match[2]);
+ if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)
+ || numerator <= 0 || denominator <= 0) return { numerator: 1, denominator: 1 };
+ const factor = divisor(numerator, denominator);
+ return { numerator: numerator / factor, denominator: denominator / factor };
+}
+
+function numeric(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) return Number(value);
+ return undefined;
+}
+
+function displayRotation(stream: FfprobeStream, index: number): 0 | 90 | 180 | 270 {
+ const sideData = stream.side_data_list?.map(object).find((item) => item?.side_data_type === "Display Matrix");
+ const raw = numeric(sideData?.rotation) ?? numeric(stream.tags?.rotate) ?? 0;
+ const normalized = ((raw % 360) + 360) % 360;
+ for (const quarter of [0, 90, 180, 270] as const) {
+ if (Math.abs(normalized - quarter) < 1e-6) return quarter;
+ }
+ throw new Error(`video stream ${index} uses unsupported non-quarter display rotation ${raw}`);
+}
+
function timestamp(ticks: bigint, timeBase: MediaRational): MediaTimestamp {
return { ticks: ticks.toString(), timeBase };
}
@@ -222,6 +260,8 @@ export function parseMediaInspection(args: {
role,
width,
height,
+ sampleAspectRatio: sampleAspectRatio(stream.sample_aspect_ratio),
+ rotationDegrees: displayRotation(stream, index),
...(rational(stream.avg_frame_rate, true) === undefined ? {} : { averageFrameRate: rational(stream.avg_frame_rate, true)! }),
...(rational(stream.r_frame_rate, true) === undefined ? {} : { nominalFrameRate: rational(stream.r_frame_rate, true)! }),
};
diff --git a/packages/media-execution/test/probe.test.ts b/packages/media-execution/test/probe.test.ts
index afa377b6..33726c2a 100644
--- a/packages/media-execution/test/probe.test.ts
+++ b/packages/media-execution/test/probe.test.ts
@@ -55,3 +55,38 @@ test("probe derives the last decoded-unit duration instead of adding whole-strea
assert.equal(video?.endPts?.ticks, "120", "last video frame should inherit the preceding 40-tick cadence");
assert.equal(audio?.endPts?.ticks, "510", "480 samples at 48kHz equal 10 ticks in a 1/1000 time base");
});
+
+test("probe preserves square-pixel and quarter-turn facts needed before Spatial", () => {
+ const source = {
+ kind: "blob" as const,
+ digest: digestOf("probe-display-geometry-fixture"),
+ size: 1,
+ mediaType: "video/mp4",
+ };
+ const value = {
+ format: { format_name: "mov,mp4" },
+ streams: [{
+ index: 0, codec_type: "video", codec_name: "h264", width: 160, height: 96,
+ sample_aspect_ratio: "8:4", time_base: "1/1000", avg_frame_rate: "25/1", r_frame_rate: "25/1",
+ disposition: { default: 1, attached_pic: 0 },
+ side_data_list: [{ side_data_type: "Display Matrix", rotation: -90 }],
+ }],
+ frames: [
+ { media_type: "video", stream_index: 0, pts: 0 },
+ { media_type: "video", stream_index: 0, pts: 40 },
+ ],
+ };
+ const inspection = parseMediaInspection({ source, ffprobeVersion: "ffprobe fixture", value });
+ const video = inspection.streams[0];
+ assert.equal(video?.kind, "video");
+ if (video?.kind !== "video") return;
+ assert.deepEqual(video.sampleAspectRatio, { numerator: 2, denominator: 1 });
+ assert.equal(video.rotationDegrees, 270);
+ assert.throws(() => parseMediaInspection({
+ source, ffprobeVersion: "ffprobe fixture",
+ value: {
+ ...value,
+ streams: [{ ...value.streams[0], side_data_list: [{ side_data_type: "Display Matrix", rotation: 45 }] }],
+ },
+ }), /unsupported non-quarter display rotation/u);
+});
diff --git a/packages/media-pipeline/test/selection.test.ts b/packages/media-pipeline/test/selection.test.ts
index 31a20cdf..ecbe94c0 100644
--- a/packages/media-pipeline/test/selection.test.ts
+++ b/packages/media-pipeline/test/selection.test.ts
@@ -38,6 +38,8 @@ function grokInspection(): MediaInspection {
role: "moving",
width: 464,
height: 688,
+ sampleAspectRatio: { numerator: 1, denominator: 1 },
+ rotationDegrees: 0,
averageFrameRate: { numerator: 24, denominator: 1 },
nominalFrameRate: { numerator: 24, denominator: 1 },
},
@@ -71,6 +73,8 @@ function grokInspection(): MediaInspection {
role: "attached-picture",
width: 464,
height: 688,
+ sampleAspectRatio: { numerator: 1, denominator: 1 },
+ rotationDegrees: 0,
},
],
});
diff --git a/packages/media-track/src/index.ts b/packages/media-track/src/index.ts
index dff41d96..a80b05d9 100644
--- a/packages/media-track/src/index.ts
+++ b/packages/media-track/src/index.ts
@@ -1,4 +1,12 @@
export { mediaTrackComponent } from "./component.js";
+export {
+ decodeMediaFit,
+ decodeMediaFramePaint,
+ decodeMediaMotion,
+ decodeMediaPresentation,
+ decodeMediaSampleSpec,
+ mediaAppearanceKeys,
+} from "./author.js";
export { renderMediaTrackFragment, stillMediaTrackFragment } from "./fragment.js";
export {
appendMediaPaintLayer,
@@ -17,6 +25,8 @@ export {
export { lowerMediaItemElements } from "./lower.js";
export {
mediaItemSpecSchema,
+ mediaFramePresentationSchema,
+ mediaLifecycleMotionSchema,
mediaLayerSetSchema,
mediaHandoffSpecSchema,
mediaPaintLayerSpecSchema,
diff --git a/packages/media-track/src/lower.ts b/packages/media-track/src/lower.ts
index a06ed02b..db5f6937 100644
--- a/packages/media-track/src/lower.ts
+++ b/packages/media-track/src/lower.ts
@@ -2,6 +2,7 @@ import type {
VisualAnimation,
VisualElement,
VisualStyleDeclaration,
+ VisualTimedSampling,
} from "@narratage/composition";
import type { ProgramSpace } from "@narratage/program-space";
import { fitContent } from "@narratage/spatial";
@@ -117,6 +118,8 @@ function sampleElements(
parent: string,
order: { value: number },
space: ProgramSpace,
+ samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
+ samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
): VisualElement[] {
const content = fitContent(innerFrame(item), layer.source.extent, layer.fit).contentFrame;
const wrapper = `${layer.id}:sampling`;
@@ -135,9 +138,14 @@ function sampleElements(
order: order.value++,
kind: "box",
style: wrapperStyle,
- ...(layer.samplingMotion === undefined ? {} : {
- animation: samplingAnimation(layer.samplingMotion, durationFrames),
- }),
+ ...(() => {
+ const override = samplingAnimationOverrides[layer.id];
+ if (override === null) return {};
+ if (override !== undefined) return { animation: override };
+ return layer.samplingMotion === undefined ? {} : {
+ animation: samplingAnimation(layer.samplingMotion, durationFrames),
+ };
+ })(),
};
// Blur samples are overscanned inside the owned frame before clipping. The
// Gaussian kernel therefore never invents a transparent/dark border and still
@@ -179,14 +187,14 @@ function sampleElements(
style: mediaStyle,
}];
}
- const sampling = resolveVisualSampling({
- space,
- sourceFrameRate: sourceTiming.frameRate,
- sourceFrameCount: sourceTiming.frameCount,
- targetFrameCount: durationFrames,
- ...(layer.trim === undefined ? {} : { trim: layer.trim }),
- occupancy: layer.occupancy!,
- });
+ const sampling = samplingOverrides[layer.id] ?? resolveVisualSampling({
+ space,
+ sourceFrameRate: sourceTiming.frameRate,
+ sourceFrameCount: sourceTiming.frameCount,
+ targetFrameCount: durationFrames,
+ ...(layer.trim === undefined ? {} : { trim: layer.trim }),
+ occupancy: layer.occupancy!,
+ });
if (layer.source.kind === "timed") {
return [wrapperElement, {
id: layer.id,
@@ -216,8 +224,12 @@ function layerElements(
parent: string,
order: { value: number },
space: ProgramSpace,
+ samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
+ samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
): VisualElement[] {
- if (layer.kind === "sample") return sampleElements(layer, item, parent, order, space);
+ if (layer.kind === "sample") {
+ return sampleElements(layer, item, parent, order, space, samplingOverrides, samplingAnimationOverrides);
+ }
return [{
id: layer.id,
parent,
@@ -244,6 +256,11 @@ export function lowerMediaItemElements(
readonly handoffAnimation?: VisualAnimation;
readonly lifecycleAnimationOverride?: VisualAnimation | null;
readonly sustainAnimationsOverride?: readonly (VisualAnimation | null)[];
+ /** Implementation-level reuse hook for collection components with their own explicit clock. */
+ readonly samplingOverrides?: Readonly<Record<string, VisualTimedSampling>>;
+ readonly samplingAnimationOverrides?: Readonly<Record<string, VisualAnimation | null>>;
+ /** Attach the Media placement subtree below another component-owned wrapper. */
+ readonly placementParent?: string;
} = {},
): readonly VisualElement[] {
const durationFrames = item.span.endFrameExclusive - item.span.startFrame;
@@ -251,6 +268,7 @@ export function lowerMediaItemElements(
const root = `${item.id}:placement`;
const elements: VisualElement[] = [{
id: root,
+ ...(options.placementParent === undefined ? {} : { parent: options.placementParent }),
order: order.value++,
kind: "box",
style: [
@@ -281,6 +299,16 @@ export function lowerMediaItemElements(
}
const frame = `${item.id}:frame`;
elements.push({ id: frame, parent, order: order.value++, kind: "box", style: frameStyles(item.presentation) });
- for (const layer of item.layers) elements.push(...layerElements(layer, item, frame, order, space));
+ for (const layer of item.layers) {
+ elements.push(...layerElements(
+ layer,
+ item,
+ frame,
+ order,
+ space,
+ options.samplingOverrides ?? {},
+ options.samplingAnimationOverrides ?? {},
+ ));
+ }
return elements;
}
diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.ts
index f6550322..6f3ab99a 100644
--- a/packages/media-track/src/manifest.ts
+++ b/packages/media-track/src/manifest.ts
@@ -163,7 +163,7 @@ const clip: ValueSchema = { kind: "oneOf", variants: [
object({ kind: { schema: { kind: "literal", value: "path" } }, path: { schema: path } }),
] };
const padding = object({ topPx: { schema: unsigned }, rightPx: { schema: unsigned }, bottomPx: { schema: unsigned }, leftPx: { schema: unsigned } });
-const presentation = object({
+export const mediaFramePresentationSchema: ValueSchema = object({
clip: { schema: clip }, padding: { schema: padding },
border: { schema: object({ widthPx: { schema: unsigned }, style: { schema: { kind: "string", enum: ["solid", "dashed", "dotted"] } }, color: { schema: string } }), optional: true },
shadows: { schema: { kind: "array", items: object({ offsetX: { schema: number }, offsetY: { schema: number }, blurPx: { schema: unsigned }, spreadPx: { schema: number }, color: { schema: string } }) } },
@@ -179,7 +179,7 @@ const sustainMotion = object({
amount: { schema: unsigned }, cycles: { schema: positiveInteger },
direction: { schema: { kind: "string", enum: ["left", "right", "up", "down"] }, optional: true },
});
-const lifecycle = object({
+export const mediaLifecycleMotionSchema: ValueSchema = object({
enter: { schema: edgeMotion, optional: true }, sustain: { schema: { kind: "array", items: sustainMotion } },
exit: { schema: edgeMotion, optional: true },
});
@@ -200,7 +200,7 @@ export const mediaSoundSetSchema: ValueSchema = object({
export const mediaItemSpecSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.media-item-spec@1" } }, id: { schema: string },
projection: { schema: projection }, expansion: { schema: object({ kind: { schema: { kind: "string", enum: ["one", "each"] } } }) },
- presentation: { schema: presentation }, motion: { schema: lifecycle }, stackingOrder: { schema: integer },
+ presentation: { schema: mediaFramePresentationSchema }, motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
sourceAudio: { schema: object({ fromLayer: { schema: string }, gain: { schema: unsigned } }), optional: true },
});
const sourceAudio = object({ fromLayer: { schema: string }, gain: { schema: unsigned } });
@@ -230,14 +230,14 @@ export const mediaHandoffSpecSchema: ValueSchema = object({
});
export const mediaSequenceSpecSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.media-sequence-spec@1" } },
- id: { schema: string }, presentation: { schema: presentation },
- motion: { schema: lifecycle }, stackingOrder: { schema: integer },
+ id: { schema: string }, presentation: { schema: mediaFramePresentationSchema },
+ motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
handoffs: { schema: { kind: "array", minItems: 1, items: mediaHandoffSpecSchema } },
});
const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: positiveInteger } });
const resolvedItem = object({
id: { schema: string }, sourceOccurrenceId: { schema: string }, span: { schema: frameSpan }, frame: { schema: spatialFrameSchema },
- presentation: { schema: presentation }, layers: { schema: { kind: "array", minItems: 1, items: layer } }, motion: { schema: lifecycle },
+ presentation: { schema: mediaFramePresentationSchema }, layers: { schema: { kind: "array", minItems: 1, items: layer } }, motion: { schema: mediaLifecycleMotionSchema },
stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
sourceAudio: { schema: object({ fromLayer: { schema: string }, gain: { schema: unsigned } }), optional: true },
sounds: { schema: { kind: "array", items: soundEvent } },
@@ -250,10 +250,10 @@ const resolvedMember = object({
const resolvedHandoff = object({ ...handoffFields, span: { schema: frameSpan } });
const resolvedSequence = object({
id: { schema: string }, span: { schema: frameSpan }, terminalFrame: { schema: positiveInteger },
- frame: { schema: spatialFrameSchema }, presentation: { schema: presentation },
+ frame: { schema: spatialFrameSchema }, presentation: { schema: mediaFramePresentationSchema },
members: { schema: { kind: "array", minItems: 2, items: resolvedMember } },
handoffs: { schema: { kind: "array", minItems: 1, items: resolvedHandoff } },
- motion: { schema: lifecycle }, stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
+ motion: { schema: mediaLifecycleMotionSchema }, stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
sounds: { schema: { kind: "array", items: soundEvent } },
});
export const mediaTrackSetSchema: ValueSchema = object({
diff --git a/packages/media/src/identity.ts b/packages/media/src/identity.ts
index bed2d914..5363e929 100644
--- a/packages/media/src/identity.ts
+++ b/packages/media/src/identity.ts
@@ -90,6 +90,10 @@ function verifyStream(value: unknown, subject: string): asserts value is MediaSt
assert(item.role === "moving" || item.role === "attached-picture" || item.role === "still", `${subject}.role is invalid`);
positiveInteger(item.width, `${subject}.width`);
positiveInteger(item.height, `${subject}.height`);
+ verifyRational(item.sampleAspectRatio, `${subject}.sampleAspectRatio`);
+ assert(item.rotationDegrees === 0 || item.rotationDegrees === 90
+ || item.rotationDegrees === 180 || item.rotationDegrees === 270,
+ `${subject}.rotationDegrees is invalid`);
if (item.averageFrameRate !== undefined) verifyRational(item.averageFrameRate, `${subject}.averageFrameRate`);
if (item.nominalFrameRate !== undefined) verifyRational(item.nominalFrameRate, `${subject}.nominalFrameRate`);
if (item.role === "attached-picture") {
diff --git a/packages/media/src/schema.ts b/packages/media/src/schema.ts
index b886b3c4..64454e62 100644
--- a/packages/media/src/schema.ts
+++ b/packages/media/src/schema.ts
@@ -20,7 +20,9 @@ const streamBase = {
} as const;
const videoStream = object({ ...streamBase, kind: { schema: { kind: "literal", value: "video" } }, codecType: { schema: { kind: "literal", value: "video" } },
role: { schema: { kind: "string", enum: ["moving", "attached-picture", "still"] } }, width: { schema: { kind: "number", integer: true, minimum: 1 } },
- height: { schema: { kind: "number", integer: true, minimum: 1 } }, averageFrameRate: { schema: rational, optional: true }, nominalFrameRate: { schema: rational, optional: true } });
+ height: { schema: { kind: "number", integer: true, minimum: 1 } }, sampleAspectRatio: { schema: rational },
+ rotationDegrees: { schema: { kind: "oneOf", variants: [0, 90, 180, 270].map((value) => ({ kind: "literal", value })) } },
+ averageFrameRate: { schema: rational, optional: true }, nominalFrameRate: { schema: rational, optional: true } });
const audioStream = object({ ...streamBase, kind: { schema: { kind: "literal", value: "audio" } }, codecType: { schema: { kind: "literal", value: "audio" } },
sampleRate: { schema: { kind: "number", integer: true, minimum: 1 } }, channels: { schema: { kind: "number", integer: true, minimum: 1 } },
channelLayout: { schema: string, optional: true }, decodedSampleFrames: { schema: integer } });
diff --git a/packages/media/src/types.ts b/packages/media/src/types.ts
index 7d577543..0e5a0253 100644
--- a/packages/media/src/types.ts
+++ b/packages/media/src/types.ts
@@ -41,6 +41,9 @@ export type MediaVideoStream = MediaStreamBase & {
readonly role: "moving" | "attached-picture" | "still";
readonly width: number;
readonly height: number;
+ /** Coded-pixel width/height become display geometry only after this ratio and rotation are normalized. */
+ readonly sampleAspectRatio: MediaRational;
+ readonly rotationDegrees: 0 | 90 | 180 | 270;
readonly averageFrameRate?: MediaRational;
readonly nominalFrameRate?: MediaRational;
};
diff --git a/packages/provider-media-local/test/provider.test.ts b/packages/provider-media-local/test/provider.test.ts
index d4ab9f6b..29b7fec3 100644
--- a/packages/provider-media-local/test/provider.test.ts
+++ b/packages/provider-media-local/test/provider.test.ts
@@ -259,6 +259,48 @@ test("local media Provider enumerates attached pictures and jointly normalizes 3
}
});
+test("local media normalization materializes rotation and sample aspect before Spatial", {
+ skip: !hasMediaBinaries,
+}, async () => {
+ const root = await mkdtemp(join(tmpdir(), "svml-provider-media-display-geometry-"));
+ try {
+ const base = join(root, "base.mp4");
+ const sourcePath = join(root, "rotated.mp4");
+ await run("ffmpeg", [
+ "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=160x96:r=4:d=0.5",
+ "-vf", "setsar=2/1", "-c:v", "libx264", "-pix_fmt", "yuv420p", base,
+ ]);
+ await run("ffmpeg", [
+ "-v", "error", "-y", "-display_rotation", "90", "-i", base, "-c", "copy", sourcePath,
+ ]);
+ const artifacts = new MemoryArtifactStore();
+ const source = await artifacts.put(await readFile(sourcePath), "video/mp4");
+ const inspection = await inspectArtifact(artifacts, source);
+ const inputVideo = inspection.streams.find((stream) => stream.kind === "video");
+ assert.equal(inputVideo?.kind, "video");
+ if (inputVideo?.kind !== "video") return;
+ assert.deepEqual(inputVideo.sampleAspectRatio, { numerator: 2, denominator: 1 });
+ assert.equal(inputVideo.rotationDegrees, 90);
+ const request = sealMediaSelectionRequest({
+ contract: "svml.media-selection-request@1",
+ video: { mode: "primary-moving" }, audio: { mode: "none" },
+ spanAuthority: "video", frameRate: { numerator: 4, denominator: 1 },
+ });
+ const selection = selectMediaStreams(inspection, request);
+ const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ assert.equal(normalized.visual?.width, 96);
+ assert.equal(normalized.visual?.height, 320);
+ const output = await inspectArtifact(artifacts, normalized.visual!.artifact);
+ const outputVideo = output.streams.find((stream) => stream.kind === "video");
+ assert.equal(outputVideo?.kind, "video");
+ if (outputVideo?.kind !== "video") return;
+ assert.deepEqual(outputVideo.sampleAspectRatio, { numerator: 1, denominator: 1 });
+ assert.equal(outputVideo.rotationDegrees, 0);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
test("animated WebP keeps its authored frame timing before fixed-rate normalization", {
skip: !hasMediaBinaries,
}, async () => {
diff --git a/packages/ranking/README.md b/packages/ranking/README.md
new file mode 100644
index 00000000..c2b88ecc
--- /dev/null
+++ b/packages/ranking/README.md
@@ -0,0 +1,19 @@
+# @narratage/ranking
+
+Four independent progressive-ranking author components over one private schedule utility:
+
+- `TierBoard`
+- `Column`
+- `TopThree`
+- `TypewriterList`
+
+The package owns variant-specific Programs and Styles. It consumes explicit Selection/Moment,
+SemanticMap, ProgramSpace, SpatialFrame, font, image and optional sound edges, then lowers to peer
+`VisualTrack` and optional `AudioTrack` values. It adds no Ranking field to Core, Composition or
+Visual IR.
+
+Each `*Style` declaration compiles one SVS Recipe and exact font reference into its visual Style
+plus a private named `.sound` Style output. A Ranking component connects both outputs when authored
+sound exists; no sound produces no audio branch.
+
+See [`../../spec/ranking-track.md`](../../spec/ranking-track.md) for the normative pre-release model.
diff --git a/packages/ranking/package.json b/packages/ranking/package.json
new file mode 100644
index 00000000..91cdbd3b
--- /dev/null
+++ b/packages/ranking/package.json
@@ -0,0 +1,27 @@
+{
+ "name": "@narratage/ranking",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "svml": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@narratage/artifact": "workspace:*",
+ "@narratage/component-kit": "workspace:*",
+ "@narratage/composition": "workspace:*",
+ "@narratage/elaborator": "workspace:*",
+ "@narratage/media": "workspace:*",
+ "@narratage/narrative": "workspace:*",
+ "@narratage/program-space": "workspace:*",
+ "@narratage/protocol": "workspace:*",
+ "@narratage/semantic-map": "workspace:*",
+ "@narratage/spatial": "workspace:*",
+ "@narratage/svs": "workspace:*",
+ "@narratage/temporal": "workspace:*",
+ "@narratage/text": "workspace:*"
+ }
+}
diff --git a/packages/ranking/src/activation.ts b/packages/ranking/src/activation.ts
new file mode 100644
index 00000000..5b15ab63
--- /dev/null
+++ b/packages/ranking/src/activation.ts
@@ -0,0 +1,46 @@
+import { createTextSurfaceHostFacet } from "@narratage/text";
+
+import {
+ decodeColumnStyleSurface,
+ decodeColumnSurface,
+ decodeTierBoardStyleSurface,
+ decodeTierBoardSurface,
+ decodeTopThreeStyleSurface,
+ decodeTopThreeSurface,
+ decodeTypewriterListStyleSurface,
+ decodeTypewriterListSurface,
+ rankingComponent,
+ rankingManifest,
+ rankingModuleRef,
+ rankingSurfaceImplementationDigests,
+} from "./index.js";
+
+const facets = [
+ ["tier-style", rankingSurfaceImplementationDigests.tierStyle, decodeTierBoardStyleSurface],
+ ["column-style", rankingSurfaceImplementationDigests.columnStyle, decodeColumnStyleSurface],
+ ["top-three-style", rankingSurfaceImplementationDigests.topThreeStyle, decodeTopThreeStyleSurface],
+ ["typewriter-style", rankingSurfaceImplementationDigests.typewriterStyle, decodeTypewriterListStyleSurface],
+ ["tier", rankingSurfaceImplementationDigests.tier, decodeTierBoardSurface],
+ ["column", rankingSurfaceImplementationDigests.column, decodeColumnSurface],
+ ["top-three", rankingSurfaceImplementationDigests.topThree, decodeTopThreeSurface],
+ ["typewriter", rankingSurfaceImplementationDigests.typewriter, decodeTypewriterListSurface],
+] as const;
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/ranking",
+ modules: [{
+ manifest: rankingManifest,
+ specifiers: [rankingModuleRef.name, `${rankingModuleRef.name}@1`],
+ }],
+ components: [rankingComponent],
+ hostFacets: facets.map(([surface, implementationDigest, handler]) => createTextSurfaceHostFacet({
+ module: rankingModuleRef,
+ surface,
+ mode: "structured",
+ implementationDigest,
+ handler,
+ })),
+};
+
+export default svmlPackage;
diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.ts
new file mode 100644
index 00000000..69357157
--- /dev/null
+++ b/packages/ranking/src/component.ts
@@ -0,0 +1,264 @@
+import type { ComponentPackage, ProducerHandlerContext } from "@narratage/component-kit";
+import type { SynchronizedMedia } from "@narratage/media";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import type { ProgramSpace } from "@narratage/program-space";
+import { canonicalize } from "@narratage/protocol";
+import type { BlobRef, StoredValue } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import type { SpatialFrame } from "@narratage/spatial";
+
+import { rankingProducers, rankingTypes } from "./manifest.js";
+import {
+ appendColumnItem,
+ appendRankingItemSpec,
+ appendRankingSound,
+ appendTierBoardItem,
+ appendTopThreeItem,
+ appendTypewriterItem,
+ assertColumnProgram,
+ assertRankingSchedule,
+ assertRankingSoundEventPlan,
+ assertTierBoardProgram,
+ assertTopThreeProgram,
+ assertTypewriterListProgram,
+ buildColumnProgram,
+ buildColumnSoundEvents,
+ buildRankingSchedule,
+ buildTierBoardProgram,
+ buildTierBoardSoundEvents,
+ buildTopThreeProgram,
+ buildTopThreeSoundEvents,
+ buildTypewriterListProgram,
+ buildTypewriterSoundEvents,
+ createColumnItemSet,
+ createRankingItemSpecSet,
+ createRankingSoundSet,
+ createTierBoardItemSet,
+ createTopThreeItemSet,
+ createTypewriterItemSet,
+ rankingImplementationDigests,
+ rankingValidatorDigests,
+} from "./schedule.js";
+import {
+ renderColumn,
+ renderRankingAudio,
+ renderTierBoard,
+ renderTopThree,
+ renderTypewriterList,
+} from "./render.js";
+import type {
+ ColumnItemSet,
+ ColumnItemSpec,
+ ColumnProgram,
+ ColumnStyle,
+ RankingHeader,
+ RankingItemSpec,
+ RankingItemSpecSet,
+ RankingSchedule,
+ RankingSoundEventPlan,
+ RankingSoundSet,
+ RankingSoundStyle,
+ TierBoardItemSet,
+ TierBoardItemSpec,
+ TierBoardProgram,
+ TierBoardStyle,
+ TopThreeItemSet,
+ TopThreeItemSpec,
+ TopThreeProgram,
+ TopThreeStyle,
+ TypewriterItemSet,
+ TypewriterItemSpec,
+ TypewriterListProgram,
+ TypewriterListStyle,
+} from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+ if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+ return value.value as unknown as T;
+}
+
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+function programInputs(inputs: ProducerHandlerContext["inputs"]) {
+ return {
+ header: inline<RankingHeader>(inputs.header?.value, "RankingHeader"),
+ frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ schedule: inline<RankingSchedule>(inputs.schedule?.value, "RankingSchedule"),
+ };
+}
+
+export const rankingComponent = {
+ name: "@narratage/ranking",
+ producers: [
+ {
+ producer: rankingProducers.createSpecs,
+ implementationDigest: rankingImplementationDigests.createSpecs,
+ handler: ({ inputs }) => ({ outputs: { set: output(createRankingItemSpecSet(inline(inputs.header?.value, "RankingHeader"))) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.appendSpec,
+ implementationDigest: rankingImplementationDigests.appendSpec,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendRankingItemSpec(
+ inline(inputs.set?.value, "RankingItemSpecSet"), inline(inputs.spec?.value, "RankingItemSpec"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.schedule,
+ implementationDigest: rankingImplementationDigests.schedule,
+ handler: ({ inputs }) => ({ outputs: { schedule: output(buildRankingSchedule({
+ header: inline(inputs.header?.value, "RankingHeader"), items: inline(inputs.items?.value, "RankingItemSpecSet"),
+ map: inline(inputs.map?.value, "CompleteSemanticMap"), space: inline(inputs.space?.value, "ProgramSpace"),
+ outer: inline(inputs.outer?.value, "NarrativeSelectionRef"), triggers: inline(inputs.triggers?.value, "NarrativeMomentRef"),
+ terminal: inline(inputs.terminal?.value, "NarrativeMomentRef"),
+ })) }, needs: {} }),
+ },
+ ...([
+ [rankingProducers.createTierItems, rankingImplementationDigests.createTierItems, createTierBoardItemSet],
+ [rankingProducers.createColumnItems, rankingImplementationDigests.createColumnItems, createColumnItemSet],
+ [rankingProducers.createTopThreeItems, rankingImplementationDigests.createTopThreeItems, createTopThreeItemSet],
+ [rankingProducers.createTypewriterItems, rankingImplementationDigests.createTypewriterItems, createTypewriterItemSet],
+ ] as const).map(([producer, implementationDigest, create]) => ({
+ producer, implementationDigest,
+ handler: () => ({ outputs: { set: output(create()) }, needs: {} }),
+ })),
+ {
+ producer: rankingProducers.appendTierItem,
+ implementationDigest: rankingImplementationDigests.appendTierItem,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendTierBoardItem(
+ inline<TierBoardItemSet>(inputs.set?.value, "TierBoardItemSet"),
+ inline<TierBoardItemSpec>(inputs.spec?.value, "TierBoardItemSpec"),
+ inline<BlobRef>(inputs.icon?.value, "TierBoard icon"),
+ )) }, needs: {} }),
+ },
+ ...([
+ [rankingProducers.appendColumnItem, rankingImplementationDigests.appendColumnItem, false],
+ [rankingProducers.appendColumnIconItem, rankingImplementationDigests.appendColumnIconItem, true],
+ ] as const).map(([producer, implementationDigest, hasIcon]) => ({
+ producer, implementationDigest,
+ handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { set: output(appendColumnItem(
+ inline<ColumnItemSet>(inputs.set?.value, "ColumnItemSet"),
+ inline<ColumnItemSpec>(inputs.spec?.value, "ColumnItemSpec"),
+ ...(hasIcon ? [inline<BlobRef>(inputs.icon?.value, "Column icon")] : []),
+ )) }, needs: {} }),
+ })),
+ ...([
+ [rankingProducers.appendTopThreeItem, rankingImplementationDigests.appendTopThreeItem, false],
+ [rankingProducers.appendTopThreeIconItem, rankingImplementationDigests.appendTopThreeIconItem, true],
+ ] as const).map(([producer, implementationDigest, hasIcon]) => ({
+ producer, implementationDigest,
+ handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { set: output(appendTopThreeItem(
+ inline<TopThreeItemSet>(inputs.set?.value, "TopThreeItemSet"),
+ inline<TopThreeItemSpec>(inputs.spec?.value, "TopThreeItemSpec"),
+ ...(hasIcon ? [inline<BlobRef>(inputs.icon?.value, "TopThree icon")] : []),
+ )) }, needs: {} }),
+ })),
+ {
+ producer: rankingProducers.appendTypewriterItem,
+ implementationDigest: rankingImplementationDigests.appendTypewriterItem,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendTypewriterItem(
+ inline<TypewriterItemSet>(inputs.set?.value, "TypewriterItemSet"),
+ inline<TypewriterItemSpec>(inputs.spec?.value, "TypewriterItemSpec"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.tierProgram,
+ implementationDigest: rankingImplementationDigests.tierProgram,
+ handler: ({ inputs }) => {
+ const common = programInputs(inputs);
+ return { outputs: { program: output(buildTierBoardProgram(common.header, common.frame, common.schedule,
+ inline<TierBoardStyle>(inputs.style?.value, "TierBoardStyle"), inline<TierBoardItemSet>(inputs.set?.value, "TierBoardItemSet"))) }, needs: {} };
+ },
+ },
+ {
+ producer: rankingProducers.columnProgram,
+ implementationDigest: rankingImplementationDigests.columnProgram,
+ handler: ({ inputs }) => {
+ const common = programInputs(inputs);
+ return { outputs: { program: output(buildColumnProgram(common.header, common.frame, common.schedule,
+ inline<ColumnStyle>(inputs.style?.value, "ColumnStyle"), inline<ColumnItemSet>(inputs.set?.value, "ColumnItemSet"))) }, needs: {} };
+ },
+ },
+ {
+ producer: rankingProducers.topThreeProgram,
+ implementationDigest: rankingImplementationDigests.topThreeProgram,
+ handler: ({ inputs }) => {
+ const common = programInputs(inputs);
+ return { outputs: { program: output(buildTopThreeProgram(common.header, common.frame, common.schedule,
+ inline<TopThreeStyle>(inputs.style?.value, "TopThreeStyle"), inline<TopThreeItemSet>(inputs.set?.value, "TopThreeItemSet"))) }, needs: {} };
+ },
+ },
+ {
+ producer: rankingProducers.typewriterProgram,
+ implementationDigest: rankingImplementationDigests.typewriterProgram,
+ handler: ({ inputs }) => {
+ const common = programInputs(inputs);
+ const title = inline<{ readonly contract: "svml.ranking-title@1"; readonly value: string }>(inputs.title?.value, "RankingTitle");
+ return { outputs: { program: output(buildTypewriterListProgram(common.header, title.value, common.frame, common.schedule,
+ inline<TypewriterListStyle>(inputs.style?.value, "TypewriterListStyle"), inline<TypewriterItemSet>(inputs.set?.value, "TypewriterItemSet"))) }, needs: {} };
+ },
+ },
+ ...([
+ [rankingProducers.tierEvents, rankingImplementationDigests.tierEvents, buildTierBoardSoundEvents, "TierBoardStyle"],
+ [rankingProducers.columnEvents, rankingImplementationDigests.columnEvents, buildColumnSoundEvents, "ColumnStyle"],
+ [rankingProducers.topThreeEvents, rankingImplementationDigests.topThreeEvents, buildTopThreeSoundEvents, "TopThreeStyle"],
+ [rankingProducers.typewriterEvents, rankingImplementationDigests.typewriterEvents, buildTypewriterSoundEvents, "TypewriterListStyle"],
+ ] as const).map(([producer, implementationDigest, build, styleLabel]) => ({
+ producer, implementationDigest,
+ handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { events: output(build(
+ inline(inputs.schedule?.value, "RankingSchedule"),
+ inline(inputs.style?.value, styleLabel) as never,
+ inline(inputs.specs?.value, "RankingItemSpecSet"),
+ )) }, needs: {} }),
+ })),
+ {
+ producer: rankingProducers.createSounds,
+ implementationDigest: rankingImplementationDigests.createSounds,
+ handler: () => ({ outputs: { sounds: output(createRankingSoundSet()) }, needs: {} }),
+ },
+ ...([
+ [rankingProducers.appendAppearSound, rankingImplementationDigests.appendAppearSound, "appear"],
+ [rankingProducers.appendMoveSound, rankingImplementationDigests.appendMoveSound, "move"],
+ ] as const).map(([producer, implementationDigest, kind]) => ({
+ producer, implementationDigest,
+ handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { sounds: output(appendRankingSound(
+ inline<RankingSoundSet>(inputs.sounds?.value, "RankingSoundSet"), kind,
+ inline<SynchronizedMedia>(inputs.media?.value, `Ranking ${kind} sound`),
+ )) }, needs: {} }),
+ })),
+ {
+ producer: rankingProducers.renderAudio,
+ implementationDigest: rankingImplementationDigests.renderAudio,
+ handler: ({ inputs }) => ({ outputs: { track: output(renderRankingAudio(
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<RankingSoundEventPlan>(inputs.events?.value, "RankingSoundEventPlan"),
+ inline<RankingSoundStyle>(inputs.style?.value, "RankingSoundStyle"),
+ inline<RankingSoundSet>(inputs.sounds?.value, "RankingSoundSet"),
+ )) }, needs: {} }),
+ },
+ ...([
+ [rankingProducers.renderTier, rankingImplementationDigests.renderTier, renderTierBoard, "TierBoardProgram"],
+ [rankingProducers.renderColumn, rankingImplementationDigests.renderColumn, renderColumn, "ColumnProgram"],
+ [rankingProducers.renderTopThree, rankingImplementationDigests.renderTopThree, renderTopThree, "TopThreeProgram"],
+ [rankingProducers.renderTypewriter, rankingImplementationDigests.renderTypewriter, renderTypewriterList, "TypewriterListProgram"],
+ ] as const).map(([producer, implementationDigest, render, label]) => ({
+ producer, implementationDigest,
+ handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { track: output(render(
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline(inputs.program?.value, label) as never,
+ )) }, needs: {} }),
+ })),
+ ],
+ validators: [
+ { type: rankingTypes.schedule, implementationDigest: rankingValidatorDigests.schedule,
+ handler: ({ value }) => assertRankingSchedule(inline<RankingSchedule>(value, "RankingSchedule")) },
+ { type: rankingTypes.tierProgram, implementationDigest: rankingValidatorDigests.tierProgram,
+ handler: ({ value }) => assertTierBoardProgram(inline<TierBoardProgram>(value, "TierBoardProgram")) },
+ { type: rankingTypes.columnProgram, implementationDigest: rankingValidatorDigests.columnProgram,
+ handler: ({ value }) => assertColumnProgram(inline<ColumnProgram>(value, "ColumnProgram")) },
+ { type: rankingTypes.topThreeProgram, implementationDigest: rankingValidatorDigests.topThreeProgram,
+ handler: ({ value }) => assertTopThreeProgram(inline<TopThreeProgram>(value, "TopThreeProgram")) },
+ { type: rankingTypes.typewriterProgram, implementationDigest: rankingValidatorDigests.typewriterProgram,
+ handler: ({ value }) => assertTypewriterListProgram(inline<TypewriterListProgram>(value, "TypewriterListProgram")) },
+ { type: rankingTypes.soundEvents, implementationDigest: rankingValidatorDigests.events,
+ handler: ({ value }) => assertRankingSoundEventPlan(inline<RankingSoundEventPlan>(value, "RankingSoundEventPlan")) },
+ ],
+} satisfies ComponentPackage;
diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.ts
new file mode 100644
index 00000000..2e2054ac
--- /dev/null
+++ b/packages/ranking/src/fragment.ts
@@ -0,0 +1,180 @@
+import { compositionTypes } from "@narratage/composition";
+import { sealGraphFragment } from "@narratage/elaborator";
+import type { FragmentOperation, GraphFragment } from "@narratage/elaborator";
+import { mediaTypes } from "@narratage/media";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes } from "@narratage/program-space";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { spatialTypes } from "@narratage/spatial";
+
+import { rankingProducers, rankingTypes } from "./manifest.js";
+import type { RankingVariant } from "./types.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export type RankingFragmentItem = {
+ readonly suffix: string;
+ readonly specName: string;
+ readonly iconName?: string;
+};
+
+export type RankingFragmentSound = {
+ readonly appearName?: string;
+ readonly moveName?: string;
+};
+
+const definition = (variant: RankingVariant) => {
+ if (variant === "tier-board") return {
+ style: rankingTypes.tierStyle, set: rankingTypes.tierItems, program: rankingTypes.tierProgram,
+ create: rankingProducers.createTierItems, append: rankingProducers.appendTierItem,
+ appendIcon: rankingProducers.appendTierItem, build: rankingProducers.tierProgram,
+ events: rankingProducers.tierEvents, render: rankingProducers.renderTier,
+ } as const;
+ if (variant === "column") return {
+ style: rankingTypes.columnStyle, set: rankingTypes.columnItems, program: rankingTypes.columnProgram,
+ create: rankingProducers.createColumnItems, append: rankingProducers.appendColumnItem,
+ appendIcon: rankingProducers.appendColumnIconItem, build: rankingProducers.columnProgram,
+ events: rankingProducers.columnEvents, render: rankingProducers.renderColumn,
+ } as const;
+ if (variant === "top-three") return {
+ style: rankingTypes.topThreeStyle, set: rankingTypes.topThreeItems, program: rankingTypes.topThreeProgram,
+ create: rankingProducers.createTopThreeItems, append: rankingProducers.appendTopThreeItem,
+ appendIcon: rankingProducers.appendTopThreeIconItem, build: rankingProducers.topThreeProgram,
+ events: rankingProducers.topThreeEvents, render: rankingProducers.renderTopThree,
+ } as const;
+ return {
+ style: rankingTypes.typewriterStyle, set: rankingTypes.typewriterItems, program: rankingTypes.typewriterProgram,
+ create: rankingProducers.createTypewriterItems, append: rankingProducers.appendTypewriterItem,
+ appendIcon: rankingProducers.appendTypewriterItem, build: rankingProducers.typewriterProgram,
+ events: rankingProducers.typewriterEvents, render: rankingProducers.renderTypewriter,
+ } as const;
+};
+
+export function createRankingFragment(
+ variant: RankingVariant,
+ items: readonly RankingFragmentItem[],
+ sound: RankingFragmentSound,
+ name = `@narratage/ranking/dynamic-${variant}@1`,
+) {
+ if (items.length === 0) throw new Error("Ranking Fragment requires at least one Item.");
+ const selected = definition(variant);
+ const inputs: Array<GraphFragment["inputs"][number]> = [
+ { name: "header", type: rankingTypes.header },
+ { name: "map", type: semanticMapTypes.complete },
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "outer", type: narrativeTypes.selection },
+ { name: "triggers", type: narrativeTypes.moment },
+ { name: "terminal", type: narrativeTypes.moment },
+ { name: "frame", type: spatialTypes.frame },
+ { name: "style", type: selected.style },
+ ];
+ if (variant === "typewriter-list") inputs.push({ name: "title", type: rankingTypes.title });
+ const operations: FragmentOperation[] = [
+ { id: "specs", producer: rankingProducers.createSpecs, inputs: { header: input("header") }, result: { kind: "output", name: "set" } },
+ { id: "resolved", producer: selected.create, inputs: {}, result: { kind: "output", name: "set" } },
+ ];
+ let specs = operation("specs");
+ let resolved = operation("resolved");
+ for (const item of items) {
+ inputs.push({ name: item.specName, type: rankingTypes.itemSpec });
+ if (item.iconName !== undefined) inputs.push({ name: item.iconName, type: mediaTypes.blobArtifact });
+ const semanticId = `spec-${item.suffix}`;
+ operations.push({
+ id: semanticId,
+ producer: rankingProducers.appendSpec,
+ inputs: { set: specs, spec: input(item.specName) },
+ result: { kind: "output", name: "set" },
+ });
+ specs = operation(semanticId);
+ const visualId = `item-${item.suffix}`;
+ operations.push({
+ id: visualId,
+ producer: item.iconName === undefined ? selected.append : selected.appendIcon,
+ inputs: {
+ set: resolved,
+ spec: input(item.specName),
+ ...(item.iconName === undefined ? {} : { icon: input(item.iconName) }),
+ },
+ result: { kind: "output", name: "set" },
+ });
+ resolved = operation(visualId);
+ }
+ operations.push({
+ id: "schedule",
+ producer: rankingProducers.schedule,
+ inputs: {
+ header: input("header"), items: specs, map: input("map"), space: input("space"),
+ outer: input("outer"), triggers: input("triggers"), terminal: input("terminal"),
+ },
+ result: { kind: "output", name: "schedule" },
+ });
+ operations.push({
+ id: "program",
+ producer: selected.build,
+ inputs: {
+ header: input("header"),
+ ...(variant === "typewriter-list" ? { title: input("title") } : {}),
+ frame: input("frame"), schedule: operation("schedule"), style: input("style"), set: resolved,
+ },
+ result: { kind: "output", name: "program" },
+ });
+ operations.push({
+ id: "visual",
+ producer: selected.render,
+ inputs: { space: input("space"), program: operation("program") },
+ result: { kind: "output", name: "track" },
+ });
+ const hasAudio = sound.appearName !== undefined || sound.moveName !== undefined;
+ if (hasAudio) {
+ inputs.push({ name: "sound-style", type: rankingTypes.soundStyle });
+ operations.push({
+ id: "events", producer: selected.events,
+ inputs: { schedule: operation("schedule"), style: input("style"), specs },
+ result: { kind: "output", name: "events" },
+ });
+ operations.push({
+ id: "sounds", producer: rankingProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" },
+ });
+ let sounds = operation("sounds");
+ for (const [kind, inputName, producer] of [
+ ["appear", sound.appearName, rankingProducers.appendAppearSound],
+ ["move", sound.moveName, rankingProducers.appendMoveSound],
+ ] as const) {
+ if (inputName === undefined) continue;
+ inputs.push({ name: inputName, type: mediaTypes.synchronized });
+ const id = `sound-${kind}`;
+ operations.push({
+ id, producer, inputs: { sounds, media: input(inputName) }, result: { kind: "output", name: "sounds" },
+ });
+ sounds = operation(id);
+ }
+ operations.push({
+ id: "audio", producer: rankingProducers.renderAudio,
+ inputs: { space: input("space"), events: operation("events"), style: input("sound-style"), sounds },
+ result: { kind: "output", name: "track" },
+ });
+ }
+ const scheduleSemanticInputs = ["header", "map", "space", "outer", "triggers", "terminal", ...items.map((item) => item.specName)];
+ const visualSemanticInputs = [
+ ...scheduleSemanticInputs, "frame", "style",
+ ...(variant === "typewriter-list" ? ["title"] : []),
+ ...items.flatMap((item) => item.iconName === undefined ? [] : [item.iconName]),
+ ];
+ const audioSemanticInputs = [
+ ...scheduleSemanticInputs, "style", "sound-style",
+ ...(sound.appearName === undefined ? [] : [sound.appearName]),
+ ...(sound.moveName === undefined ? [] : [sound.moveName]),
+ ];
+ return sealGraphFragment({
+ name,
+ inputs,
+ operations,
+ exports: [
+ { name: "schedule", type: rankingTypes.schedule, root: operation("schedule"), semanticInputs: scheduleSemanticInputs, fidelity: "exact" },
+ { name: "program", type: selected.program, root: operation("program"), semanticInputs: visualSemanticInputs, fidelity: "exact" },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("visual"), semanticInputs: visualSemanticInputs, fidelity: "exact" },
+ ...(hasAudio ? [{ name: "audio", type: compositionTypes.audioTrack, root: operation("audio"), semanticInputs: audioSemanticInputs, fidelity: "exact" as const }] : []),
+ ],
+ });
+}
diff --git a/packages/ranking/src/index.ts b/packages/ranking/src/index.ts
new file mode 100644
index 00000000..ab2e53c8
--- /dev/null
+++ b/packages/ranking/src/index.ts
@@ -0,0 +1,85 @@
+export {
+ appendRankingItemSpec,
+ appendRankingSound,
+ appendColumnItem,
+ appendTierBoardItem,
+ appendTopThreeItem,
+ appendTypewriterItem,
+ assertColumnProgram,
+ assertColumnStyle,
+ assertRankingHeader,
+ assertRankingItemSpec,
+ assertRankingItemSpecSet,
+ assertRankingSchedule,
+ assertRankingSoundEventPlan,
+ assertRankingSoundStyle,
+ assertTierBoardProgram,
+ assertTierBoardStyle,
+ assertTopThreeProgram,
+ assertTopThreeStyle,
+ assertTypewriterListProgram,
+ assertTypewriterListStyle,
+ buildColumnProgram,
+ buildColumnSoundEvents,
+ buildRankingSchedule,
+ buildTierBoardProgram,
+ buildTierBoardSoundEvents,
+ buildTopThreeProgram,
+ buildTopThreeSoundEvents,
+ buildTypewriterListProgram,
+ buildTypewriterSoundEvents,
+ createColumnItemSet,
+ createRankingItemSpecSet,
+ createRankingSoundSet,
+ createTierBoardItemSet,
+ createTopThreeItemSet,
+ createTypewriterItemSet,
+ graphemes,
+ rankingImplementationDigests,
+ rankingValidatorDigests,
+ sealRankingHeader,
+} from "./schedule.js";
+export {
+ decodeColumnStyle,
+ decodeTierBoardStyle,
+ decodeTopThreeStyle,
+ decodeTypewriterListStyle,
+} from "./style.js";
+export {
+ renderColumn,
+ renderRankingAudio,
+ renderTierBoard,
+ renderTopThree,
+ renderTypewriterList,
+} from "./render.js";
+export { rankingComponent } from "./component.js";
+export { createRankingFragment } from "./fragment.js";
+export type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
+export {
+ rankingDependency,
+ rankingHeaderSchema,
+ rankingItemSpecSchema,
+ rankingItemSpecSetSchema,
+ rankingManifest,
+ rankingManifestDigest,
+ rankingModuleRef,
+ rankingProducers,
+ rankingScheduleSchema,
+ rankingSoundEventsSchema,
+ rankingSoundSetSchema,
+ rankingSoundStyleSchema,
+ rankingSurfaceImplementationDigests,
+ rankingTitleSchema,
+ rankingTypes,
+} from "./manifest.js";
+export {
+ decodeColumnStyleSurface,
+ decodeColumnSurface,
+ decodeTierBoardStyleSurface,
+ decodeTierBoardSurface,
+ decodeTopThreeStyleSurface,
+ decodeTopThreeSurface,
+ decodeTypewriterListStyleSurface,
+ decodeTypewriterListSurface,
+} from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
new file mode 100644
index 00000000..1d14bdd0
--- /dev/null
+++ b/packages/ranking/src/manifest.ts
@@ -0,0 +1,240 @@
+import { artifactDependency } from "@narratage/artifact";
+import { compositionDependency, compositionTypes } from "@narratage/composition";
+import { mediaDependency, mediaTypes } from "@narratage/media";
+import { narrativeDependency, narrativeTypes } from "@narratage/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@narratage/program-space";
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
+import { semanticMapDependency, semanticMapTypes } from "@narratage/semantic-map";
+import { spatialDependency, spatialFrameSchema, spatialTypes } from "@narratage/spatial";
+import { temporalDependency } from "@narratage/temporal";
+
+import { rankingImplementationDigests, rankingValidatorDigests } from "./schedule.js";
+
+export const rankingModuleRef = { name: "@narratage/ranking", version: "0.0.0-dev" } as const;
+export const rankingTypes = {
+ header: { module: rankingModuleRef, name: "RankingHeader" },
+ itemSpec: { module: rankingModuleRef, name: "RankingItemSpec" },
+ itemSpecs: { module: rankingModuleRef, name: "RankingItemSpecSet" },
+ schedule: { module: rankingModuleRef, name: "RankingSchedule" },
+ soundStyle: { module: rankingModuleRef, name: "RankingSoundStyle" },
+ soundEvents: { module: rankingModuleRef, name: "RankingSoundEventPlan" },
+ sounds: { module: rankingModuleRef, name: "RankingSoundSet" },
+ tierStyle: { module: rankingModuleRef, name: "TierBoardStyle" },
+ columnStyle: { module: rankingModuleRef, name: "ColumnStyle" },
+ topThreeStyle: { module: rankingModuleRef, name: "TopThreeStyle" },
+ typewriterStyle: { module: rankingModuleRef, name: "TypewriterListStyle" },
+ tierItems: { module: rankingModuleRef, name: "TierBoardItemSet" },
+ columnItems: { module: rankingModuleRef, name: "ColumnItemSet" },
+ topThreeItems: { module: rankingModuleRef, name: "TopThreeItemSet" },
+ typewriterItems: { module: rankingModuleRef, name: "TypewriterItemSet" },
+ tierProgram: { module: rankingModuleRef, name: "TierBoardProgram" },
+ columnProgram: { module: rankingModuleRef, name: "ColumnProgram" },
+ topThreeProgram: { module: rankingModuleRef, name: "TopThreeProgram" },
+ typewriterProgram: { module: rankingModuleRef, name: "TypewriterListProgram" },
+ title: { module: rankingModuleRef, name: "RankingTitle" },
+} satisfies Record<string, TypeRef>;
+
+export const rankingProducers = {
+ createSpecs: { module: rankingModuleRef, name: "create-ranking-item-specs" },
+ appendSpec: { module: rankingModuleRef, name: "append-ranking-item-spec" },
+ schedule: { module: rankingModuleRef, name: "build-ranking-schedule" },
+ createTierItems: { module: rankingModuleRef, name: "create-tier-board-items" },
+ appendTierItem: { module: rankingModuleRef, name: "append-tier-board-item" },
+ createColumnItems: { module: rankingModuleRef, name: "create-column-items" },
+ appendColumnItem: { module: rankingModuleRef, name: "append-column-item" },
+ appendColumnIconItem: { module: rankingModuleRef, name: "append-column-icon-item" },
+ createTopThreeItems: { module: rankingModuleRef, name: "create-top-three-items" },
+ appendTopThreeItem: { module: rankingModuleRef, name: "append-top-three-item" },
+ appendTopThreeIconItem: { module: rankingModuleRef, name: "append-top-three-icon-item" },
+ createTypewriterItems: { module: rankingModuleRef, name: "create-typewriter-items" },
+ appendTypewriterItem: { module: rankingModuleRef, name: "append-typewriter-item" },
+ tierProgram: { module: rankingModuleRef, name: "build-tier-board-program" },
+ columnProgram: { module: rankingModuleRef, name: "build-column-program" },
+ topThreeProgram: { module: rankingModuleRef, name: "build-top-three-program" },
+ typewriterProgram: { module: rankingModuleRef, name: "build-typewriter-list-program" },
+ tierEvents: { module: rankingModuleRef, name: "build-tier-board-sound-events" },
+ columnEvents: { module: rankingModuleRef, name: "build-column-sound-events" },
+ topThreeEvents: { module: rankingModuleRef, name: "build-top-three-sound-events" },
+ typewriterEvents: { module: rankingModuleRef, name: "build-typewriter-list-sound-events" },
+ createSounds: { module: rankingModuleRef, name: "create-ranking-sounds" },
+ appendAppearSound: { module: rankingModuleRef, name: "append-ranking-appear-sound" },
+ appendMoveSound: { module: rankingModuleRef, name: "append-ranking-move-sound" },
+ renderAudio: { module: rankingModuleRef, name: "render-ranking-audio" },
+ renderTier: { module: rankingModuleRef, name: "render-tier-board" },
+ renderColumn: { module: rankingModuleRef, name: "render-column" },
+ renderTopThree: { module: rankingModuleRef, name: "render-top-three" },
+ renderTypewriter: { module: rankingModuleRef, name: "render-typewriter-list" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true } as const;
+const unsigned = { kind: "number", integer: true, minimum: 0 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>, allowUnknown = false): ValueSchema => ({
+ kind: "object", fields, ...(allowUnknown ? { allowUnknown: true } : {}),
+});
+const variants = { kind: "string", enum: ["tier-board", "column", "top-three", "typewriter-list"] } as const;
+const itemBase = {
+ id: { schema: string },
+ stackingOrder: { schema: integer, optional: true },
+} as const;
+export const rankingHeaderSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-header@1" } }, id: { schema: string }, variant: { schema: variants },
+});
+export const rankingItemSpecSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ contract: { schema: { kind: "literal", value: "svml.tier-board-item-spec@1" } }, variant: { schema: { kind: "literal", value: "tier-board" } }, ...itemBase, tier: { schema: string }, entry: { schema: { kind: "string", enum: ["direct", "stage"] } } }),
+ object({ contract: { schema: { kind: "literal", value: "svml.column-item-spec@1" } }, variant: { schema: { kind: "literal", value: "column" } }, ...itemBase, label: { schema: string } }),
+ object({ contract: { schema: { kind: "literal", value: "svml.top-three-item-spec@1" } }, variant: { schema: { kind: "literal", value: "top-three" } }, ...itemBase, label: { schema: string } }),
+ object({ contract: { schema: { kind: "literal", value: "svml.typewriter-item-spec@1" } }, variant: { schema: { kind: "literal", value: "typewriter-list" } }, ...itemBase,
+ text: { schema: string }, winner: { schema: { kind: "boolean" } },
+ emphasis: { optional: true, schema: object({ start: { schema: unsigned }, endExclusive: { schema: unsigned } }) },
+ }),
+] };
+export const rankingItemSpecSetSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-item-spec-set@1" } },
+ variant: { schema: variants }, items: { schema: { kind: "array", items: rankingItemSpecSchema } },
+});
+const frameSpan = object({ startFrame: { schema: unsigned }, endFrameExclusive: { schema: unsigned } });
+export const rankingScheduleSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-schedule@1" } }, id: { schema: string },
+ variant: { schema: variants }, outer: { schema: frameSpan }, terminalFrame: { schema: unsigned },
+ entries: { schema: { kind: "array", minItems: 1, items: object({
+ itemId: { schema: string }, triggerOccurrenceId: { schema: string }, triggerFrame: { schema: unsigned },
+ stage: { schema: frameSpan }, cumulative: { schema: frameSpan }, settled: { schema: frameSpan },
+ }) } },
+});
+const styleSchema = (contract: string): ValueSchema => object({ contract: { schema: { kind: "literal", value: contract } } }, true);
+const setSchema = (contract: string): ValueSchema => object({
+ contract: { schema: { kind: "literal", value: contract } }, items: { schema: { kind: "array", items: object({}, true) } },
+});
+const programSchema = (contract: string): ValueSchema => object({
+ contract: { schema: { kind: "literal", value: contract } }, id: { schema: string }, frame: { schema: spatialFrameSchema },
+ schedule: { schema: rankingScheduleSchema }, style: { schema: object({}, true) }, items: { schema: { kind: "array", minItems: 1, items: object({}, true) } },
+}, true);
+export const rankingSoundStyleSchema = styleSchema("svml.ranking-sound-style@1");
+export const rankingSoundEventsSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-sound-event-plan@1" } }, id: { schema: string }, variant: { schema: variants },
+ events: { schema: { kind: "array", items: object({ id: { schema: string }, itemId: { schema: string }, kind: { schema: { kind: "string", enum: ["appear", "move"] } }, frame: { schema: unsigned } }) } },
+});
+export const rankingSoundSetSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-sound-set@1" } },
+ appear: { schema: object({}, true), optional: true }, move: { schema: object({}, true), optional: true },
+});
+export const rankingTitleSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.ranking-title@1" } }, value: { schema: string },
+});
+
+export const rankingSurfaceImplementationDigests = {
+ tierStyle: digestOf("@narratage/ranking/tier-board-style-surface@1"),
+ columnStyle: digestOf("@narratage/ranking/column-style-surface@1"),
+ topThreeStyle: digestOf("@narratage/ranking/top-three-style-surface@1"),
+ typewriterStyle: digestOf("@narratage/ranking/typewriter-list-style-surface@1"),
+ tier: digestOf("@narratage/ranking/tier-board-surface@1"),
+ column: digestOf("@narratage/ranking/column-surface@1"),
+ topThree: digestOf("@narratage/ranking/top-three-surface@1"),
+ typewriter: digestOf("@narratage/ranking/typewriter-list-surface@1"),
+} as const;
+const registered = (locator: string, digest: ReturnType<typeof digestOf>) => ({ kind: "registered" as const, locator, digest });
+const validator = (locator: string, digest: ReturnType<typeof digestOf>) => ({ abi: "svml.type-validator@1" as const, implementation: registered(locator, digest) });
+
+const programDefinitions = [
+ ["tier", rankingTypes.tierProgram, rankingTypes.tierStyle, rankingTypes.tierItems, rankingProducers.tierProgram, rankingProducers.tierEvents, rankingProducers.renderTier, rankingImplementationDigests.tierProgram, rankingImplementationDigests.tierEvents, rankingImplementationDigests.renderTier],
+ ["column", rankingTypes.columnProgram, rankingTypes.columnStyle, rankingTypes.columnItems, rankingProducers.columnProgram, rankingProducers.columnEvents, rankingProducers.renderColumn, rankingImplementationDigests.columnProgram, rankingImplementationDigests.columnEvents, rankingImplementationDigests.renderColumn],
+ ["top-three", rankingTypes.topThreeProgram, rankingTypes.topThreeStyle, rankingTypes.topThreeItems, rankingProducers.topThreeProgram, rankingProducers.topThreeEvents, rankingProducers.renderTopThree, rankingImplementationDigests.topThreeProgram, rankingImplementationDigests.topThreeEvents, rankingImplementationDigests.renderTopThree],
+ ["typewriter", rankingTypes.typewriterProgram, rankingTypes.typewriterStyle, rankingTypes.typewriterItems, rankingProducers.typewriterProgram, rankingProducers.typewriterEvents, rankingProducers.renderTypewriter, rankingImplementationDigests.typewriterProgram, rankingImplementationDigests.typewriterEvents, rankingImplementationDigests.renderTypewriter],
+] as const;
+
+export const rankingManifest: ModuleManifest = {
+ format: "svml.module@1", name: rankingModuleRef.name, version: rankingModuleRef.version,
+ dependencies: [artifactDependency, mediaDependency, narrativeDependency, semanticMapDependency, programSpaceDependency, spatialDependency, temporalDependency, compositionDependency],
+ types: [
+ { name: rankingTypes.header.name, schema: rankingHeaderSchema },
+ { name: rankingTypes.itemSpec.name, schema: rankingItemSpecSchema },
+ { name: rankingTypes.itemSpecs.name, schema: rankingItemSpecSetSchema },
+ { name: rankingTypes.schedule.name, schema: rankingScheduleSchema, validator: validator("@narratage/ranking/validate-schedule", rankingValidatorDigests.schedule) },
+ { name: rankingTypes.soundStyle.name, schema: rankingSoundStyleSchema },
+ { name: rankingTypes.soundEvents.name, schema: rankingSoundEventsSchema, validator: validator("@narratage/ranking/validate-sound-events", rankingValidatorDigests.events) },
+ { name: rankingTypes.sounds.name, schema: rankingSoundSetSchema },
+ { name: rankingTypes.tierStyle.name, schema: styleSchema("svml.tier-board-style@1") },
+ { name: rankingTypes.columnStyle.name, schema: styleSchema("svml.column-style@1") },
+ { name: rankingTypes.topThreeStyle.name, schema: styleSchema("svml.top-three-style@1") },
+ { name: rankingTypes.typewriterStyle.name, schema: styleSchema("svml.typewriter-list-style@1") },
+ { name: rankingTypes.tierItems.name, schema: setSchema("svml.tier-board-item-set@1") },
+ { name: rankingTypes.columnItems.name, schema: setSchema("svml.column-item-set@1") },
+ { name: rankingTypes.topThreeItems.name, schema: setSchema("svml.top-three-item-set@1") },
+ { name: rankingTypes.typewriterItems.name, schema: setSchema("svml.typewriter-item-set@1") },
+ { name: rankingTypes.tierProgram.name, schema: programSchema("svml.tier-board-program@1"), validator: validator("@narratage/ranking/validate-tier-board-program", rankingValidatorDigests.tierProgram) },
+ { name: rankingTypes.columnProgram.name, schema: programSchema("svml.column-program@1"), validator: validator("@narratage/ranking/validate-column-program", rankingValidatorDigests.columnProgram) },
+ { name: rankingTypes.topThreeProgram.name, schema: programSchema("svml.top-three-program@1"), validator: validator("@narratage/ranking/validate-top-three-program", rankingValidatorDigests.topThreeProgram) },
+ { name: rankingTypes.typewriterProgram.name, schema: programSchema("svml.typewriter-list-program@1"), validator: validator("@narratage/ranking/validate-typewriter-list-program", rankingValidatorDigests.typewriterProgram) },
+ { name: rankingTypes.title.name, schema: rankingTitleSchema },
+ ],
+ capabilities: [],
+ surfaces: [
+ { name: "tier-style", tag: "TierBoardStyle", mode: "structured", outputs: [rankingTypes.tierStyle, rankingTypes.soundStyle], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/tier-board-style-surface", digest: rankingSurfaceImplementationDigests.tierStyle } },
+ { name: "column-style", tag: "ColumnStyle", mode: "structured", outputs: [rankingTypes.columnStyle, rankingTypes.soundStyle], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/column-style-surface", digest: rankingSurfaceImplementationDigests.columnStyle } },
+ { name: "top-three-style", tag: "TopThreeStyle", mode: "structured", outputs: [rankingTypes.topThreeStyle, rankingTypes.soundStyle], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/top-three-style-surface", digest: rankingSurfaceImplementationDigests.topThreeStyle } },
+ { name: "typewriter-style", tag: "TypewriterListStyle", mode: "structured", outputs: [rankingTypes.typewriterStyle, rankingTypes.soundStyle], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/typewriter-list-style-surface", digest: rankingSurfaceImplementationDigests.typewriterStyle } },
+ { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, compositionTypes.audioTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/tier-board-surface", digest: rankingSurfaceImplementationDigests.tier } },
+ { name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, compositionTypes.audioTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/column-surface", digest: rankingSurfaceImplementationDigests.column } },
+ { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, compositionTypes.audioTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/top-three-surface", digest: rankingSurfaceImplementationDigests.topThree } },
+ { name: "typewriter", tag: "TypewriterList", mode: "structured", outputs: [rankingTypes.schedule, rankingTypes.typewriterProgram, compositionTypes.visualTrack, compositionTypes.audioTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/ranking/typewriter-list-surface", digest: rankingSurfaceImplementationDigests.typewriter } },
+ ],
+ producers: [
+ { name: rankingProducers.createSpecs.name, inputs: [{ name: "header", type: rankingTypes.header }], outputs: [{ name: "set", type: rankingTypes.itemSpecs }], needs: [], implementation: registered("@narratage/ranking/create-item-specs", rankingImplementationDigests.createSpecs) },
+ { name: rankingProducers.appendSpec.name, inputs: [{ name: "set", type: rankingTypes.itemSpecs }, { name: "spec", type: rankingTypes.itemSpec }], outputs: [{ name: "set", type: rankingTypes.itemSpecs }], needs: [], implementation: registered("@narratage/ranking/append-item-spec", rankingImplementationDigests.appendSpec) },
+ { name: rankingProducers.schedule.name, inputs: [
+ { name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },
+ { name: "map", type: semanticMapTypes.complete }, { name: "space", type: programSpaceTypes.programSpace },
+ { name: "outer", type: narrativeTypes.selection }, { name: "triggers", type: narrativeTypes.moment }, { name: "terminal", type: narrativeTypes.moment },
+ ], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [], implementation: registered("@narratage/ranking/build-schedule", rankingImplementationDigests.schedule) },
+ ...([
+ [rankingProducers.createTierItems, rankingTypes.tierItems, rankingImplementationDigests.createTierItems, "@narratage/ranking/create-tier-items"],
+ [rankingProducers.createColumnItems, rankingTypes.columnItems, rankingImplementationDigests.createColumnItems, "@narratage/ranking/create-column-items"],
+ [rankingProducers.createTopThreeItems, rankingTypes.topThreeItems, rankingImplementationDigests.createTopThreeItems, "@narratage/ranking/create-top-three-items"],
+ [rankingProducers.createTypewriterItems, rankingTypes.typewriterItems, rankingImplementationDigests.createTypewriterItems, "@narratage/ranking/create-typewriter-items"],
+ ] as const).map(([producer, type, implementationDigest, locator]) => ({
+ name: producer.name, inputs: [], outputs: [{ name: "set", type }], needs: [], implementation: registered(locator, implementationDigest),
+ })),
+ { name: rankingProducers.appendTierItem.name, inputs: [{ name: "set", type: rankingTypes.tierItems }, { name: "spec", type: rankingTypes.itemSpec }, { name: "icon", type: mediaTypes.blobArtifact }], outputs: [{ name: "set", type: rankingTypes.tierItems }], needs: [], implementation: registered("@narratage/ranking/append-tier-item", rankingImplementationDigests.appendTierItem) },
+ ...([
+ [rankingProducers.appendColumnItem, rankingTypes.columnItems, rankingImplementationDigests.appendColumnItem, "@narratage/ranking/append-column-item"],
+ [rankingProducers.appendTopThreeItem, rankingTypes.topThreeItems, rankingImplementationDigests.appendTopThreeItem, "@narratage/ranking/append-top-three-item"],
+ ] as const).map(([producer, type, implementationDigest, locator]) => ({
+ name: producer.name, inputs: [{ name: "set", type }, { name: "spec", type: rankingTypes.itemSpec }], outputs: [{ name: "set", type }], needs: [], implementation: registered(locator, implementationDigest),
+ })),
+ ...([
+ [rankingProducers.appendColumnIconItem, rankingTypes.columnItems, rankingImplementationDigests.appendColumnIconItem, "@narratage/ranking/append-column-icon-item"],
+ [rankingProducers.appendTopThreeIconItem, rankingTypes.topThreeItems, rankingImplementationDigests.appendTopThreeIconItem, "@narratage/ranking/append-top-three-icon-item"],
+ ] as const).map(([producer, type, implementationDigest, locator]) => ({
+ name: producer.name, inputs: [{ name: "set", type }, { name: "spec", type: rankingTypes.itemSpec }, { name: "icon", type: mediaTypes.blobArtifact }], outputs: [{ name: "set", type }], needs: [], implementation: registered(locator, implementationDigest),
+ })),
+ { name: rankingProducers.appendTypewriterItem.name, inputs: [{ name: "set", type: rankingTypes.typewriterItems }, { name: "spec", type: rankingTypes.itemSpec }], outputs: [{ name: "set", type: rankingTypes.typewriterItems }], needs: [], implementation: registered("@narratage/ranking/append-typewriter-item", rankingImplementationDigests.appendTypewriterItem) },
+ ...programDefinitions.flatMap(([name, programType, styleType, setType, programProducer, eventProducer, renderProducer, programDigest, eventDigest, renderDigest]) => [
+ { name: programProducer.name, inputs: [
+ { name: "header", type: rankingTypes.header },
+ ...(name === "typewriter" ? [{ name: "title", type: rankingTypes.title }] : []),
+ { name: "frame", type: spatialTypes.frame }, { name: "schedule", type: rankingTypes.schedule },
+ { name: "style", type: styleType }, { name: "set", type: setType },
+ ], outputs: [{ name: "program", type: programType }], needs: [], implementation: registered(`@narratage/ranking/build-${name}-program`, programDigest) },
+ { name: eventProducer.name, inputs: [
+ { name: "schedule", type: rankingTypes.schedule }, { name: "style", type: styleType }, { name: "specs", type: rankingTypes.itemSpecs },
+ ], outputs: [{ name: "events", type: rankingTypes.soundEvents }], needs: [], implementation: registered(`@narratage/ranking/build-${name}-events`, eventDigest) },
+ { name: renderProducer.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: programType }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [], implementation: registered(`@narratage/ranking/render-${name}`, renderDigest) },
+ ]),
+ { name: rankingProducers.createSounds.name, inputs: [], outputs: [{ name: "sounds", type: rankingTypes.sounds }], needs: [], implementation: registered("@narratage/ranking/create-sounds", rankingImplementationDigests.createSounds) },
+ ...([
+ [rankingProducers.appendAppearSound, rankingImplementationDigests.appendAppearSound, "@narratage/ranking/append-appear-sound"],
+ [rankingProducers.appendMoveSound, rankingImplementationDigests.appendMoveSound, "@narratage/ranking/append-move-sound"],
+ ] as const).map(([producer, implementationDigest, locator]) => ({
+ name: producer.name, inputs: [{ name: "sounds", type: rankingTypes.sounds }, { name: "media", type: mediaTypes.synchronized }], outputs: [{ name: "sounds", type: rankingTypes.sounds }], needs: [], implementation: registered(locator, implementationDigest),
+ })),
+ { name: rankingProducers.renderAudio.name, inputs: [
+ { name: "space", type: programSpaceTypes.programSpace }, { name: "events", type: rankingTypes.soundEvents },
+ { name: "style", type: rankingTypes.soundStyle }, { name: "sounds", type: rankingTypes.sounds },
+ ], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [], implementation: registered("@narratage/ranking/render-audio", rankingImplementationDigests.renderAudio) },
+ ],
+};
+
+export const rankingManifestDigest = digestOf(rankingManifest);
+export const rankingDependency = { module: rankingModuleRef, digest: rankingManifestDigest } as const;
diff --git a/packages/ranking/src/render.ts b/packages/ranking/src/render.ts
new file mode 100644
index 00000000..ffae0de1
--- /dev/null
+++ b/packages/ranking/src/render.ts
@@ -0,0 +1,699 @@
+import {
+ assertAudioTrackIdentity,
+ assertVisualTrackIdentity,
+ sealAudioTrack,
+ sealVisualTrack,
+} from "@narratage/composition";
+import type {
+ AudioClip,
+ AudioTrack,
+ VisualAnimation,
+ VisualElement,
+ VisualPresent,
+ VisualStyleDeclaration,
+ VisualTextDocument,
+ VisualTextFlow,
+ VisualTextPaintLayer,
+ VisualTextTypography,
+ VisualTrack,
+} from "@narratage/composition";
+import { verifySynchronizedMedia } from "@narratage/media";
+import {
+ assertProgramSpaceIdentity,
+ programFrameSampleBoundary,
+ programSpaceSampleFrames,
+} from "@narratage/program-space";
+import type { ProgramSpace } from "@narratage/program-space";
+
+import {
+ assertColumnProgram,
+ assertRankingSoundEventPlan,
+ assertRankingSoundStyle,
+ assertTierBoardProgram,
+ assertTopThreeProgram,
+ assertTypewriterListProgram,
+ graphemes,
+} from "./schedule.js";
+import type {
+ ColumnItem,
+ ColumnProgram,
+ RankingBoardPaint,
+ RankingSoundEventPlan,
+ RankingSoundSet,
+ RankingSoundStyle,
+ RankingTextStyle,
+ TierBoardItem,
+ TierBoardProgram,
+ TopThreeItem,
+ TopThreeProgram,
+ TypewriterItem,
+ TypewriterListProgram,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function px(value: number): string {
+ return `${Math.round(value * 1_000_000) / 1_000_000}px`;
+}
+
+function boxShadow(value: RankingBoardPaint["shadow"]): string {
+ return `${px(value.offsetX)} ${px(value.offsetY)} ${px(value.blurPx)} ${px(value.spreadPx)} ${value.color}`;
+}
+
+function absoluteBox(input: {
+ readonly id: string;
+ readonly order: number;
+ readonly parent?: string;
+ readonly x: number;
+ readonly y: number;
+ readonly width: number;
+ readonly height: number;
+ readonly style?: readonly VisualStyleDeclaration[];
+ readonly animation?: VisualAnimation;
+}): VisualElement {
+ return {
+ id: input.id,
+ ...(input.parent === undefined ? {} : { parent: input.parent }),
+ order: input.order,
+ kind: "box",
+ style: [
+ { name: "height", value: px(input.height) },
+ { name: "left", value: px(input.x) },
+ { name: "position", value: "absolute" },
+ { name: "top", value: px(input.y) },
+ { name: "width", value: px(input.width) },
+ ...(input.style ?? []),
+ ],
+ ...(input.animation === undefined ? {} : { animation: input.animation }),
+ };
+}
+
+function boardStyle(value: RankingBoardPaint): VisualStyleDeclaration[] {
+ return [
+ { name: "background", value: value.background },
+ { name: "border", value: `${px(value.borderWidthPx)} solid ${value.borderColor}` },
+ { name: "border-radius", value: px(value.radiusPx) },
+ { name: "box-shadow", value: boxShadow(value.shadow) },
+ { name: "box-sizing", value: "border-box" },
+ { name: "overflow", value: "hidden" },
+ ];
+}
+
+function textStyle(value: RankingTextStyle, align: "left" | "center" | "right" = "center"): VisualStyleDeclaration[] {
+ return [
+ { name: "align-items", value: "center" },
+ { name: "color", value: value.color },
+ { name: "display", value: "flex" },
+ { name: "font-size", value: px(value.sizePx) },
+ { name: "justify-content", value: align === "left" ? "start" : align === "right" ? "end" : "center" },
+ { name: "line-height", value: value.lineHeight },
+ { name: "overflow", value: "hidden" },
+ { name: "text-align", value: align },
+ { name: "white-space", value: "nowrap" },
+ ];
+}
+
+function simpleText(input: {
+ readonly id: string;
+ readonly order: number;
+ readonly parent?: string;
+ readonly text: string;
+ readonly typography: RankingTextStyle;
+ readonly x: number;
+ readonly y: number;
+ readonly width: number;
+ readonly height: number;
+ readonly align?: "left" | "center" | "right";
+ readonly style?: readonly VisualStyleDeclaration[];
+ readonly animation?: VisualAnimation;
+}): VisualElement {
+ return {
+ id: input.id,
+ ...(input.parent === undefined ? {} : { parent: input.parent }),
+ order: input.order,
+ kind: "text",
+ text: input.text,
+ fonts: structuredClone(input.typography.fonts),
+ style: [
+ { name: "height", value: px(input.height) },
+ { name: "left", value: px(input.x) },
+ { name: "position", value: "absolute" },
+ { name: "top", value: px(input.y) },
+ { name: "width", value: px(input.width) },
+ ...textStyle(input.typography, input.align),
+ ...(input.style ?? []),
+ ],
+ ...(input.animation === undefined ? {} : { animation: input.animation }),
+ };
+}
+
+function iconElement(input: {
+ readonly id: string;
+ readonly order: number;
+ readonly parent: string;
+ readonly artifact: TierBoardItem["icon"];
+ readonly x: number;
+ readonly y: number;
+ readonly size: number;
+ readonly radius: number;
+ readonly fit: "contain" | "cover";
+}): VisualElement {
+ return {
+ id: input.id,
+ parent: input.parent,
+ order: input.order,
+ kind: "image",
+ artifact: structuredClone(input.artifact),
+ style: [
+ { name: "border-radius", value: px(input.radius) },
+ { name: "height", value: px(input.size) },
+ { name: "left", value: px(input.x) },
+ { name: "object-fit", value: input.fit },
+ { name: "overflow", value: "hidden" },
+ { name: "position", value: "absolute" },
+ { name: "top", value: px(input.y) },
+ { name: "width", value: px(input.size) },
+ ],
+ };
+}
+
+function present(input: {
+ readonly id: string;
+ readonly start: number;
+ readonly end: number;
+ readonly stacking: number;
+ readonly tieBreak: string;
+ readonly elements: readonly VisualElement[];
+}): VisualPresent {
+ return {
+ id: input.id,
+ span: { startFrame: input.start, endFrameExclusive: input.end },
+ stacking: { order: input.stacking, tieBreak: input.tieBreak },
+ elements: input.elements,
+ };
+}
+
+function animation(
+ duration: number,
+ values: readonly { readonly atFrame: number; readonly style: readonly VisualStyleDeclaration[]; readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" }[],
+): VisualAnimation {
+ const ordered = [...values, ...(values.at(-1)?.atFrame === duration ? [] : [{ atFrame: duration, style: values.at(-1)!.style }])];
+ const unique: typeof ordered = [];
+ for (const value of ordered) {
+ const previous = unique.at(-1);
+ if (previous?.atFrame === value.atFrame) unique[unique.length - 1] = value;
+ else unique.push(value);
+ }
+ assert(unique[0]?.atFrame === 0 && unique.at(-1)?.atFrame === duration, "Ranking animation does not span its Present.");
+ return { keyframes: unique };
+}
+
+function transformStyle(transform: string, opacity: number): VisualStyleDeclaration[] {
+ return [{ name: "opacity", value: opacity }, { name: "transform", value: transform }];
+}
+
+function finalTransform(): string {
+ return "translate(0px,0px) scale(1)";
+}
+
+function stageTransform(finalX: number, finalY: number, stageX: number, stageY: number, scale: number): string {
+ return `translate(${px(stageX - finalX)},${px(stageY - finalY)}) scale(${scale})`;
+}
+
+function settledItemAnimation(input: {
+ readonly duration: number;
+ readonly appearFrames: number;
+ readonly moveStart: number;
+ readonly moveEnd: number;
+ readonly stageTransform: string;
+ readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+}): VisualAnimation {
+ return animation(input.duration, [
+ { atFrame: 0, style: transformStyle(`${input.stageTransform} scale(0.82)`, 0), easing: "ease-out" },
+ { atFrame: input.appearFrames, style: transformStyle(input.stageTransform, 1) },
+ { atFrame: input.moveStart, style: transformStyle(input.stageTransform, 1), easing: input.easing },
+ { atFrame: input.moveEnd, style: transformStyle(finalTransform(), 1) },
+ ]);
+}
+
+function directItemAnimation(duration: number, appearFrames: number): VisualAnimation {
+ return animation(duration, [
+ { atFrame: 0, style: transformStyle("translate(0px,8px) scale(0.82)", 0), easing: "ease-out" },
+ { atFrame: appearFrames, style: transformStyle(finalTransform(), 1) },
+ ]);
+}
+
+function sealTrack(space: ProgramSpace, id: string, presents: readonly VisualPresent[]): VisualTrack {
+ const value = sealVisualTrack({ contract: "svml.visual-track@1", visualIr: "svml.visual-ir@1", id, presents });
+ assertVisualTrackIdentity(value, space);
+ return value;
+}
+
+export function renderTierBoard(space: ProgramSpace, program: TierBoardProgram): VisualTrack {
+ assertProgramSpaceIdentity(space);
+ assertTierBoardProgram(program);
+ const { frame, style, schedule } = program;
+ const presents: VisualPresent[] = [];
+ const boardElements: VisualElement[] = [absoluteBox({
+ id: "tier-board", order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
+ style: boardStyle(style.board),
+ })];
+ for (const [index, row] of style.rows.entries()) {
+ const y = style.paddingPx + index * (style.rowHeightPx + style.rowGapPx);
+ boardElements.push(absoluteBox({
+ id: `tier-row-${row.id}`, parent: "tier-board", order: boardElements.length,
+ x: style.paddingPx, y, width: frame.widthPx - style.paddingPx * 2, height: style.rowHeightPx,
+ style: [{ name: "background", value: row.color }, { name: "border-radius", value: px(Math.min(12, style.iconRadiusPx)) }],
+ }));
+ boardElements.push(simpleText({
+ id: `tier-label-${row.id}`, parent: `tier-row-${row.id}`, order: boardElements.length,
+ text: row.label, typography: style.text, x: 0, y: 0, width: style.labelWidthPx, height: style.rowHeightPx,
+ }));
+ }
+ presents.push(present({
+ id: `${program.id}:board`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
+ stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements,
+ }));
+ if (program.items.some((item) => item.entry === "stage")) {
+ const size = style.stageSizePx;
+ presents.push(present({
+ id: `${program.id}:stage`, start: schedule.entries[0]!.triggerFrame, end: schedule.terminalFrame,
+ stacking: style.stageStackingOrder, tieBreak: `${program.id}:0001:stage`, elements: [absoluteBox({
+ id: "tier-stage", order: 0,
+ x: frame.xPx + frame.widthPx * style.stagePoint.x - size / 2,
+ y: frame.yPx + frame.heightPx * style.stagePoint.y - size / 2,
+ width: size, height: size,
+ style: [
+ { name: "border", value: `${px(2)} dashed ${style.text.color}` },
+ { name: "border-radius", value: px(style.iconRadiusPx) },
+ { name: "opacity", value: 0.45 },
+ ],
+ })],
+ }));
+ }
+ const rowCounts = new Map<string, number>();
+ for (const [index, item] of program.items.entries()) {
+ const entry = schedule.entries[index]!;
+ const rowIndex = style.rows.findIndex((row) => row.id === item.tier);
+ const cell = rowCounts.get(item.tier) ?? 0;
+ rowCounts.set(item.tier, cell + 1);
+ const x = frame.xPx + style.paddingPx + style.labelWidthPx + cell * (style.iconSizePx + style.cellGapPx);
+ const y = frame.yPx + style.paddingPx + rowIndex * (style.rowHeightPx + style.rowGapPx)
+ + (style.rowHeightPx - style.iconSizePx) / 2;
+ assert(x + style.iconSizePx <= frame.xPx + frame.widthPx - style.paddingPx,
+ `TierBoard row ${item.tier} cannot fit Item ${item.id}.`);
+ const duration = entry.stage.endFrameExclusive - entry.stage.startFrame;
+ const rootAnimation = item.entry === "direct"
+ ? directItemAnimation(duration, style.motion.appearFrames)
+ : settledItemAnimation({
+ duration,
+ appearFrames: style.motion.appearFrames,
+ moveStart: entry.stage.endFrameExclusive - style.motion.moveFrames - entry.triggerFrame,
+ moveEnd: entry.stage.endFrameExclusive - entry.triggerFrame,
+ stageTransform: stageTransform(
+ x, y,
+ frame.xPx + frame.widthPx * style.stagePoint.x - style.iconSizePx / 2,
+ frame.yPx + frame.heightPx * style.stagePoint.y - style.iconSizePx / 2,
+ style.stageSizePx / style.iconSizePx,
+ ),
+ easing: style.motion.easing,
+ });
+ const root = `tier-item-${item.id}`;
+ const itemElements = (animationValue?: VisualAnimation): VisualElement[] => [
+ absoluteBox({ id: root, order: 0, x, y, width: style.iconSizePx, height: style.iconSizePx,
+ ...(animationValue === undefined ? {} : { animation: animationValue }) }),
+ iconElement({ id: "icon", parent: root, order: 1, artifact: item.icon, x: 0, y: 0, size: style.iconSizePx, radius: style.iconRadiusPx, fit: style.iconFit }),
+ ];
+ presents.push(present({
+ id: `${program.id}:item:${item.id}:stage`,
+ start: entry.stage.startFrame,
+ end: entry.stage.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`,
+ elements: itemElements(rootAnimation),
+ }));
+ if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
+ id: `${program.id}:item:${item.id}:settled`,
+ start: entry.settled.startFrame,
+ end: entry.settled.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`,
+ elements: itemElements(),
+ }));
+ }
+ return sealTrack(space, program.id, presents);
+}
+
+function rowY(frameY: number, frameHeight: number, padding: number, count: number, index: number, height: number, gap: number): number {
+ const total = count * height + Math.max(0, count - 1) * gap;
+ return frameY + Math.max(padding, frameHeight - padding - total) + index * (height + gap);
+}
+
+function rankColor(colors: readonly string[], index: number): string {
+ return colors[index % colors.length]!;
+}
+
+export function renderColumn(space: ProgramSpace, program: ColumnProgram): VisualTrack {
+ assertProgramSpaceIdentity(space);
+ assertColumnProgram(program);
+ const { frame, style, schedule } = program;
+ const presents: VisualPresent[] = [];
+ const boardElements: VisualElement[] = [absoluteBox({
+ id: "column-board", order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
+ style: boardStyle(style.board),
+ })];
+ for (const [index] of program.items.entries()) {
+ const y = rowY(0, frame.heightPx, style.paddingPx, program.items.length, index, style.rowHeightPx, style.rowGapPx);
+ boardElements.push(absoluteBox({
+ id: `column-row-${index + 1}`, parent: "column-board", order: boardElements.length,
+ x: style.paddingPx, y, width: frame.widthPx - style.paddingPx * 2, height: style.rowHeightPx,
+ style: [
+ { name: "background", value: `${rankColor(style.rankColors, index)}22` },
+ { name: "border", value: `${px(1)} solid ${rankColor(style.rankColors, index)}88` },
+ { name: "border-radius", value: px(12) },
+ ],
+ }));
+ boardElements.push(simpleText({
+ id: `column-rank-${index + 1}`, parent: `column-row-${index + 1}`, order: boardElements.length,
+ text: String(index + 1), typography: { ...style.text, color: rankColor(style.rankColors, index) },
+ x: 0, y: 0, width: style.rowHeightPx, height: style.rowHeightPx,
+ }));
+ }
+ presents.push(present({ id: `${program.id}:board`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
+ stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements }));
+ const stageSize = style.stageSizePx;
+ presents.push(present({
+ id: `${program.id}:stage`, start: schedule.entries[0]!.triggerFrame, end: schedule.terminalFrame,
+ stacking: style.stageStackingOrder, tieBreak: `${program.id}:0001:stage`, elements: [absoluteBox({
+ id: "column-stage", order: 0,
+ x: frame.xPx + frame.widthPx * style.stagePoint.x - stageSize / 2,
+ y: frame.yPx + frame.heightPx * style.stagePoint.y - stageSize / 2,
+ width: stageSize, height: stageSize,
+ style: [{ name: "border", value: `${px(2)} solid ${style.text.color}66` }, { name: "border-radius", value: px(18) }],
+ })],
+ }));
+ for (const [index, item] of program.items.entries()) {
+ const entry = schedule.entries[index]!;
+ const x = frame.xPx + style.paddingPx;
+ const y = rowY(frame.yPx, frame.heightPx, style.paddingPx, program.items.length, index, style.rowHeightPx, style.rowGapPx);
+ const width = frame.widthPx - style.paddingPx * 2;
+ const duration = entry.stage.endFrameExclusive - entry.triggerFrame;
+ const targetStageX = frame.xPx + frame.widthPx * style.stagePoint.x - width / 2;
+ const targetStageY = frame.yPx + frame.heightPx * style.stagePoint.y - style.rowHeightPx / 2;
+ const root = `column-item-${item.id}`;
+ const rootAnimation = settledItemAnimation({
+ duration,
+ appearFrames: style.motion.appearFrames,
+ moveStart: entry.stage.endFrameExclusive - style.motion.moveFrames - entry.triggerFrame,
+ moveEnd: entry.stage.endFrameExclusive - entry.triggerFrame,
+ stageTransform: stageTransform(x, y, targetStageX, targetStageY, style.stageSizePx / style.rowHeightPx),
+ easing: style.motion.easing,
+ });
+ const itemElements = (animationValue?: VisualAnimation): VisualElement[] => {
+ const elements: VisualElement[] = [absoluteBox({
+ id: root, order: 0, x, y, width, height: style.rowHeightPx,
+ style: [{ name: "border-radius", value: px(12) }],
+ ...(animationValue === undefined ? {} : { animation: animationValue }),
+ })];
+ if (item.icon !== undefined) elements.push(iconElement({ id: "icon", parent: root, order: 1, artifact: item.icon,
+ x: style.rowHeightPx, y: (style.rowHeightPx - style.iconSizePx) / 2, size: style.iconSizePx,
+ radius: style.iconRadiusPx, fit: style.iconFit }));
+ elements.push(simpleText({
+ id: "label", parent: root, order: elements.length, text: item.label, typography: style.text,
+ x: style.rowHeightPx + (item.icon === undefined ? 0 : style.iconSizePx + 12), y: 0,
+ width: width - style.rowHeightPx - (item.icon === undefined ? 8 : style.iconSizePx + 20), height: style.rowHeightPx,
+ align: "left",
+ }));
+ return elements;
+ };
+ presents.push(present({
+ id: `${program.id}:item:${item.id}:stage`, start: entry.stage.startFrame, end: entry.stage.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(rootAnimation),
+ }));
+ if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
+ id: `${program.id}:item:${item.id}:settled`, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(),
+ }));
+ }
+ return sealTrack(space, program.id, presents);
+}
+
+function topSlotX(program: TopThreeProgram, index: number): number {
+ const total = program.items.length * program.style.iconSizePx + Math.max(0, program.items.length - 1) * program.style.slotGapPx;
+ return program.frame.xPx + program.frame.widthPx * program.style.centerX - total / 2
+ + index * (program.style.iconSizePx + program.style.slotGapPx);
+}
+
+function activeAccentAnimation(duration: number, activeFrames: number): VisualAnimation {
+ const middle = Math.max(1, Math.floor(activeFrames / 2));
+ return animation(duration, [
+ { atFrame: 0, style: transformStyle("scale(1)", 1), easing: "ease-in-out" },
+ { atFrame: middle, style: transformStyle("scale(1.08)", 1), easing: "ease-in-out" },
+ { atFrame: activeFrames, style: transformStyle("scale(1)", 1) },
+ ]);
+}
+
+export function renderTopThree(space: ProgramSpace, program: TopThreeProgram): VisualTrack {
+ assertProgramSpaceIdentity(space);
+ assertTopThreeProgram(program);
+ const { frame, style, schedule } = program;
+ const boardElements: VisualElement[] = [absoluteBox({
+ id: "top-slots-root", order: 0,
+ x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
+ })];
+ for (const [index] of program.items.entries()) {
+ boardElements.push(absoluteBox({
+ id: `top-slot-${index + 1}`, parent: "top-slots-root", order: index + 1,
+ x: topSlotX(program, index) - frame.xPx,
+ y: frame.heightPx * style.baselineY - style.iconSizePx / 2,
+ width: style.iconSizePx, height: style.iconSizePx,
+ style: [
+ { name: "border", value: `${px(style.ringWidthPx)} solid ${rankColor(style.slotColors, index)}55` },
+ { name: "border-radius", value: px(style.iconRadiusPx) },
+ ],
+ }));
+ }
+ const presents: VisualPresent[] = [present({
+ id: `${program.id}:slots`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
+ stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:slots`, elements: boardElements,
+ })];
+ for (const [index, item] of program.items.entries()) {
+ const entry = schedule.entries[index]!;
+ const x = topSlotX(program, index);
+ const y = frame.yPx + frame.heightPx * style.baselineY - style.iconSizePx / 2;
+ const duration = entry.stage.endFrameExclusive - entry.triggerFrame;
+ const activeFrames = entry.stage.endFrameExclusive - entry.triggerFrame;
+ const root = `top-item-${item.id}`;
+ const accent = "accent";
+ const itemElements = (active: boolean): VisualElement[] => {
+ const elements: VisualElement[] = [absoluteBox({
+ id: root, order: 0, x, y, width: style.iconSizePx,
+ height: style.iconSizePx + style.labelGapPx + style.text.sizePx * style.text.lineHeight,
+ ...(active ? { animation: directItemAnimation(duration, style.motion.appearFrames) } : {}),
+ })];
+ if (active) elements.push(absoluteBox({ id: accent, parent: root, order: 1, x: 0, y: 0, width: style.iconSizePx, height: style.iconSizePx,
+ style: [
+ { name: "border", value: `${px(style.ringWidthPx)} solid ${rankColor(style.slotColors, index)}` },
+ { name: "border-radius", value: px(style.iconRadiusPx) },
+ { name: "box-sizing", value: "border-box" },
+ ], animation: activeAccentAnimation(duration, activeFrames) }));
+ if (item.icon !== undefined) elements.push(iconElement({ id: "icon", parent: root, order: 2, artifact: item.icon,
+ x: 0, y: 0, size: style.iconSizePx, radius: style.iconRadiusPx, fit: style.iconFit }));
+ else elements.push(simpleText({ id: "rank", parent: root, order: 2, text: String(index + 1),
+ typography: { ...style.text, color: rankColor(style.slotColors, index), sizePx: style.iconSizePx * 0.45 },
+ x: 0, y: 0, width: style.iconSizePx, height: style.iconSizePx }));
+ elements.push(simpleText({ id: "label", parent: root, order: 3, text: item.label, typography: style.text,
+ x: -style.slotGapPx / 2, y: style.iconSizePx + style.labelGapPx,
+ width: style.iconSizePx + style.slotGapPx, height: style.text.sizePx * style.text.lineHeight }));
+ return elements;
+ };
+ presents.push(present({
+ id: `${program.id}:item:${item.id}:stage`, start: entry.stage.startFrame, end: entry.stage.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(true),
+ }));
+ if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
+ id: `${program.id}:item:${item.id}:settled`, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(false),
+ }));
+ }
+ return sealTrack(space, program.id, presents);
+}
+
+function visualTypography(value: RankingTextStyle): VisualTextTypography {
+ return {
+ fonts: structuredClone(value.fonts), sizePx: value.sizePx, weight: value.weight, style: "normal",
+ axes: [], features: [], synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+ lineHeight: value.lineHeight, direction: "auto", writingMode: "horizontal-tb", baselineShiftPx: 0,
+ tabSize: 4, indentationPx: 0, paragraphBeforePx: 0, paragraphAfterPx: 0, transform: "none",
+ variantCaps: "normal", verticalAlign: "baseline", decorations: [],
+ cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ };
+}
+
+const areaFlow: VisualTextFlow = {
+ form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "start", blockAlign: "center", wrap: "none", overflow: "clip", clipToFrame: true,
+ columns: 1, columnGapPx: 0, metricEdge: "line-box",
+};
+
+function typewriterDocument(item: TypewriterItem, style: TypewriterListProgram["style"]): VisualTextDocument {
+ const parts = graphemes(item.text);
+ if (item.emphasis === undefined) {
+ return { paragraphs: [{ id: `${item.id}-p`, inlines: [{ id: `${item.id}-text`, kind: "text", text: item.text }] }] };
+ }
+ const before = parts.slice(0, item.emphasis.start).join("");
+ const emphasis = parts.slice(item.emphasis.start, item.emphasis.endExclusive).join("");
+ const after = parts.slice(item.emphasis.endExclusive).join("");
+ return { paragraphs: [{
+ id: `${item.id}-p`,
+ inlines: [
+ ...(before.length === 0 ? [] : [{ id: `${item.id}-before`, kind: "text" as const, text: before }]),
+ { id: `${item.id}-emphasis`, kind: "text", text: emphasis,
+ style: { paints: [{ kind: "fill", paint: { kind: "solid", color: style.emphasisColor } }] } },
+ ...(after.length === 0 ? [] : [{ id: `${item.id}-after`, kind: "text" as const, text: after }]),
+ ],
+ }] };
+}
+
+function paperRotation(program: TypewriterListProgram): VisualStyleDeclaration[] {
+ return [
+ { name: "transform", value: `rotate(${program.style.rotationDeg}deg)` },
+ { name: "transform-origin", value: "center center" },
+ ];
+}
+
+export function renderTypewriterList(space: ProgramSpace, program: TypewriterListProgram): VisualTrack {
+ assertProgramSpaceIdentity(space);
+ assertTypewriterListProgram(program);
+ const { frame, style, schedule } = program;
+ const titleHeight = style.title.sizePx * style.title.lineHeight;
+ const rowHeight = style.item.sizePx * style.item.lineHeight;
+ const firstRowY = style.paddingPx + titleHeight + style.titleGapPx;
+ const paperElements: VisualElement[] = [absoluteBox({
+ id: "paper", order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
+ style: [...boardStyle(style.paper), ...paperRotation(program)],
+ }), simpleText({
+ id: "title", parent: "paper", order: 1, text: program.title, typography: style.title,
+ x: style.paddingPx, y: style.paddingPx, width: frame.widthPx - style.paddingPx * 2, height: titleHeight, align: "left",
+ })];
+ for (const [index] of program.items.entries()) {
+ const y = firstRowY + index * (rowHeight + style.rowGapPx);
+ assert(y + rowHeight <= frame.heightPx - style.paddingPx,
+ `TypewriterList cannot fit row ${index + 1} inside its Frame.`);
+ paperElements.push(absoluteBox({
+ id: `row-rule-${index + 1}`, parent: "paper", order: paperElements.length,
+ x: style.paddingPx, y: y + rowHeight - 1, width: frame.widthPx - style.paddingPx * 2, height: 1,
+ style: [{ name: "background", value: `${style.item.color}22` }],
+ }));
+ }
+ const presents: VisualPresent[] = [present({
+ id: `${program.id}:paper`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
+ stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:paper`, elements: paperElements,
+ })];
+ for (const [index, item] of program.items.entries()) {
+ const entry = schedule.entries[index]!;
+ const duration = entry.stage.endFrameExclusive - entry.triggerFrame;
+ const count = graphemes(item.text).length;
+ const typedFrames = count * style.framesPerGrapheme;
+ const root = `typewriter-item-${item.id}`;
+ const y = firstRowY + index * (rowHeight + style.rowGapPx);
+ const paints: VisualTextPaintLayer[] = [{ kind: "fill", paint: { kind: "solid", color: style.item.color } }];
+ const itemElements = (active: boolean): VisualElement[] => {
+ const elements: VisualElement[] = [absoluteBox({
+ id: root, order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
+ style: paperRotation(program),
+ }), {
+ id: "row-text", parent: root, order: 1, kind: "text-flow",
+ style: [
+ { name: "height", value: px(rowHeight) }, { name: "left", value: px(style.paddingPx) },
+ { name: "position", value: "absolute" }, { name: "top", value: px(y) },
+ { name: "width", value: px(frame.widthPx - style.paddingPx * 2 - rowHeight) },
+ ],
+ document: typewriterDocument(item, style), typography: visualTypography(style.item), paints,
+ flow: areaFlow,
+ sequences: active ? [{
+ id: `${item.id}-typing`, unit: "grapheme", range: { start: 0, endExclusive: count },
+ order: "forward", startFrame: 0, unitDurationFrames: 1, staggerFrames: style.framesPerGrapheme,
+ cycles: 1,
+ keyframes: [
+ { atProgress: 0, style: [{ name: "opacity", value: 0 }] },
+ { atProgress: 1, style: [{ name: "opacity", value: 1 }] },
+ ],
+ }] : [],
+ }];
+ if (item.winner) elements.push(simpleText({
+ id: "winner", parent: root, order: 2, text: "★",
+ typography: { ...style.item, color: style.winnerColor },
+ x: frame.widthPx - style.paddingPx - rowHeight, y, width: rowHeight, height: rowHeight,
+ ...(active ? { animation: animation(duration, [
+ { atFrame: 0, style: transformStyle("scale(0.5)", 0) },
+ { atFrame: typedFrames, style: transformStyle("scale(0.5)", 0), easing: "ease-out" },
+ { atFrame: typedFrames + style.winnerFrames, style: transformStyle("scale(1)", 1) },
+ ]) } : {}),
+ }));
+ return elements;
+ };
+ presents.push(present({
+ id: `${program.id}:item:${item.id}:stage`, start: entry.stage.startFrame, end: entry.stage.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(true),
+ }));
+ if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
+ id: `${program.id}:item:${item.id}:settled`, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.itemStackingOrder,
+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(false),
+ }));
+ }
+ return sealTrack(space, program.id, presents);
+}
+
+export function renderRankingAudio(
+ space: ProgramSpace,
+ plan: RankingSoundEventPlan,
+ style: RankingSoundStyle,
+ sounds: RankingSoundSet,
+): AudioTrack {
+ assertProgramSpaceIdentity(space);
+ assertRankingSoundEventPlan(plan);
+ assertRankingSoundStyle(style);
+ assert(sounds.contract === "svml.ranking-sound-set@1", "RankingSoundSet is invalid.");
+ assert(sounds.appear !== undefined || sounds.move !== undefined, "Ranking audio requires at least one authored sound.");
+ if (sounds.appear !== undefined) verifySynchronizedMedia(sounds.appear);
+ if (sounds.move !== undefined) verifySynchronizedMedia(sounds.move);
+ const totalSamples = programSpaceSampleFrames(space, 48_000);
+ const fadeSamples = programFrameSampleBoundary(space, style.fadeFrames, 48_000);
+ const clips: AudioClip[] = [];
+ for (const event of plan.events) {
+ const media = sounds[event.kind];
+ if (media === undefined) continue;
+ const audio = media.audio;
+ assert(audio !== undefined, `Ranking ${event.kind} sound has no normalized audio.`);
+ const startSample = programFrameSampleBoundary(space, event.frame, 48_000);
+ const length = Math.min(audio.sampleFrames, totalSamples - startSample);
+ assert(length > 0, `Ranking sound ${event.id} starts after ProgramSpace.`);
+ assert(fadeSamples <= length, `Ranking sound ${event.id} fade exceeds its audible interval.`);
+ clips.push({
+ id: event.id,
+ artifact: structuredClone(audio.artifact),
+ target: { startSample, endSampleExclusive: startSample + length },
+ source: { sampleFrames: audio.sampleFrames, startSample: 0, endSampleExclusive: length, loop: false, phaseSample: 0 },
+ playbackRate: 1, pitch: "preserve",
+ gain: event.kind === "appear" ? style.appearGain : style.moveGain,
+ fadeInSamples: fadeSamples, fadeOutSamples: 0,
+ });
+ }
+ for (const kind of ["appear", "move"] as const) {
+ if (sounds[kind] !== undefined) assert(clips.some((clip) => clip.id.endsWith(`:${kind}`)),
+ `Ranking ${kind} sound has no matching visual event.`);
+ }
+ const track = sealAudioTrack({ contract: "svml.audio-track@1", id: `${plan.id}.audio`, clips });
+ assertAudioTrackIdentity(track, space);
+ return track;
+}
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
new file mode 100644
index 00000000..148380d8
--- /dev/null
+++ b/packages/ranking/src/schedule.ts
@@ -0,0 +1,666 @@
+import {
+ assertFontArtifactRef,
+ verifySynchronizedMedia,
+} from "@narratage/media";
+import type { SynchronizedMedia } from "@narratage/media";
+import type {
+ NarrativeMomentRef,
+ NarrativeSelectionRef,
+} from "@narratage/narrative";
+import {
+ assertProgramSpaceIdentity,
+ programSpaceFrameCount,
+} from "@narratage/program-space";
+import type { ProgramSpace } from "@narratage/program-space";
+import { canonicalize, digestOf, isDigest } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import { assertSpatialFrame } from "@narratage/spatial";
+import {
+ locateMomentOccurrences,
+ locateSelectionOccurrences,
+ resolveTriggeredSchedule,
+} from "@narratage/temporal";
+
+import type {
+ ColumnItem,
+ ColumnItemSet,
+ ColumnItemSpec,
+ ColumnProgram,
+ ColumnStyle,
+ RankingBoardPaint,
+ RankingHeader,
+ RankingItemSpec,
+ RankingItemSpecSet,
+ RankingMotionStyle,
+ RankingSchedule,
+ RankingSoundEvent,
+ RankingSoundEventPlan,
+ RankingSoundSet,
+ RankingSoundStyle,
+ RankingTextStyle,
+ RankingVariant,
+ TierBoardItem,
+ TierBoardItemSet,
+ TierBoardItemSpec,
+ TierBoardProgram,
+ TierBoardStyle,
+ TopThreeItem,
+ TopThreeItemSet,
+ TopThreeItemSpec,
+ TopThreeProgram,
+ TopThreeStyle,
+ TypewriterItem,
+ TypewriterItemSet,
+ TypewriterItemSpec,
+ TypewriterListProgram,
+ TypewriterListStyle,
+} from "./types.js";
+
+export const rankingImplementationDigests = {
+ createSpecs: digestOf("@narratage/ranking/create-item-specs@1"),
+ appendSpec: digestOf("@narratage/ranking/append-item-spec@1"),
+ schedule: digestOf("@narratage/ranking/build-schedule@1"),
+ createTierItems: digestOf("@narratage/ranking/create-tier-items@1"),
+ appendTierItem: digestOf("@narratage/ranking/append-tier-item@1"),
+ createColumnItems: digestOf("@narratage/ranking/create-column-items@1"),
+ appendColumnItem: digestOf("@narratage/ranking/append-column-item@1"),
+ appendColumnIconItem: digestOf("@narratage/ranking/append-column-icon-item@1"),
+ createTopThreeItems: digestOf("@narratage/ranking/create-top-three-items@1"),
+ appendTopThreeItem: digestOf("@narratage/ranking/append-top-three-item@1"),
+ appendTopThreeIconItem: digestOf("@narratage/ranking/append-top-three-icon-item@1"),
+ createTypewriterItems: digestOf("@narratage/ranking/create-typewriter-items@1"),
+ appendTypewriterItem: digestOf("@narratage/ranking/append-typewriter-item@1"),
+ tierProgram: digestOf("@narratage/ranking/build-tier-board-program@1"),
+ columnProgram: digestOf("@narratage/ranking/build-column-program@1"),
+ topThreeProgram: digestOf("@narratage/ranking/build-top-three-program@1"),
+ typewriterProgram: digestOf("@narratage/ranking/build-typewriter-list-program@1"),
+ tierEvents: digestOf("@narratage/ranking/build-tier-board-sound-events@1"),
+ columnEvents: digestOf("@narratage/ranking/build-column-sound-events@1"),
+ topThreeEvents: digestOf("@narratage/ranking/build-top-three-sound-events@1"),
+ typewriterEvents: digestOf("@narratage/ranking/build-typewriter-list-sound-events@1"),
+ createSounds: digestOf("@narratage/ranking/create-sounds@1"),
+ appendAppearSound: digestOf("@narratage/ranking/append-appear-sound@1"),
+ appendMoveSound: digestOf("@narratage/ranking/append-move-sound@1"),
+ renderAudio: digestOf("@narratage/ranking/render-audio@1"),
+ renderTier: digestOf("@narratage/ranking/render-tier-board@1"),
+ renderColumn: digestOf("@narratage/ranking/render-column@1"),
+ renderTopThree: digestOf("@narratage/ranking/render-top-three@1"),
+ renderTypewriter: digestOf("@narratage/ranking/render-typewriter-list@1"),
+} as const;
+
+export const rankingValidatorDigests = {
+ schedule: digestOf("@narratage/ranking/validate-schedule@1"),
+ tierProgram: digestOf("@narratage/ranking/validate-tier-board-program@1"),
+ columnProgram: digestOf("@narratage/ranking/validate-column-program@1"),
+ topThreeProgram: digestOf("@narratage/ranking/validate-top-three-program@1"),
+ typewriterProgram: digestOf("@narratage/ranking/validate-typewriter-list-program@1"),
+ events: digestOf("@narratage/ranking/validate-sound-events@1"),
+} as const;
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function identity(value: string, label: string): void {
+ assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+
+function frame(value: number, label: string): void {
+ assert(Number.isSafeInteger(value) && value >= 0, `${label} must be a non-negative frame.`);
+}
+
+function color(value: string, label: string): void {
+ assert(value === "transparent" || /^#[0-9a-f]{3,8}$/iu.test(value), `${label} must be a hexadecimal color or transparent.`);
+}
+
+function finite(value: number, label: string): void {
+ assert(Number.isFinite(value), `${label} must be finite.`);
+}
+
+function nonNegative(value: number, label: string): void {
+ finite(value, label);
+ assert(value >= 0, `${label} must be non-negative.`);
+}
+
+function positive(value: number, label: string): void {
+ finite(value, label);
+ assert(value > 0, `${label} must be positive.`);
+}
+
+function integer(value: number, label: string, minimum = 0): void {
+ assert(Number.isSafeInteger(value) && value >= minimum, `${label} must be an integer >= ${minimum}.`);
+}
+
+function stacking(value: number, label: string): void {
+ assert(Number.isSafeInteger(value), `${label} must be an integer.`);
+}
+
+function assertBlobImage(value: { readonly digest: string; readonly size: number; readonly mediaType: string }, label: string): void {
+ assert(isDigest(value.digest) && Number.isSafeInteger(value.size) && value.size >= 0
+ && /^image\//u.test(value.mediaType), `${label} must be an image Artifact.`);
+}
+
+export function assertRankingHeader(value: RankingHeader): void {
+ assert(value.contract === "svml.ranking-header@1", "Unsupported RankingHeader contract.");
+ identity(value.id, "RankingHeader.id");
+ assert(["tier-board", "column", "top-three", "typewriter-list"].includes(value.variant),
+ "RankingHeader.variant is invalid.");
+}
+
+export function sealRankingHeader(value: RankingHeader): RankingHeader {
+ assertRankingHeader(value);
+ return canonicalize(value) as unknown as RankingHeader;
+}
+
+export function assertRankingTextStyle(value: RankingTextStyle, label: string): void {
+ assert(value.fonts.length > 0, `${label}.fonts is empty.`);
+ for (const [index, fontValue] of value.fonts.entries()) assertFontArtifactRef(fontValue, `${label}.fonts.${index}`);
+ positive(value.sizePx, `${label}.sizePx`);
+ integer(value.weight, `${label}.weight`, 1);
+ assert(value.weight <= 1_000, `${label}.weight exceeds 1000.`);
+ color(value.color, `${label}.color`);
+ positive(value.lineHeight, `${label}.lineHeight`);
+}
+
+export function assertRankingBoardPaint(value: RankingBoardPaint, label: string): void {
+ color(value.background, `${label}.background`);
+ color(value.borderColor, `${label}.borderColor`);
+ nonNegative(value.borderWidthPx, `${label}.borderWidthPx`);
+ nonNegative(value.radiusPx, `${label}.radiusPx`);
+ finite(value.shadow.offsetX, `${label}.shadow.offsetX`);
+ finite(value.shadow.offsetY, `${label}.shadow.offsetY`);
+ nonNegative(value.shadow.blurPx, `${label}.shadow.blurPx`);
+ finite(value.shadow.spreadPx, `${label}.shadow.spreadPx`);
+ color(value.shadow.color, `${label}.shadow.color`);
+}
+
+export function assertRankingMotionStyle(value: RankingMotionStyle, label: string): void {
+ integer(value.appearFrames, `${label}.appearFrames`, 1);
+ integer(value.moveFrames, `${label}.moveFrames`, 1);
+ assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.easing), `${label}.easing is invalid.`);
+}
+
+export function assertRankingSoundStyle(value: RankingSoundStyle): void {
+ assert(value.contract === "svml.ranking-sound-style@1", "Unsupported RankingSoundStyle contract.");
+ for (const [name, gain] of [["appearGain", value.appearGain], ["moveGain", value.moveGain]] as const) {
+ nonNegative(gain, `RankingSoundStyle.${name}`);
+ assert(gain <= 64, `RankingSoundStyle.${name} exceeds 64.`);
+ }
+ integer(value.fadeFrames, "RankingSoundStyle.fadeFrames");
+}
+
+function assertCommonStyle(input: {
+ readonly text: RankingTextStyle;
+ readonly motion: RankingMotionStyle;
+ readonly iconSizePx: number;
+ readonly iconRadiusPx: number;
+ readonly iconFit: "contain" | "cover";
+ readonly boardStackingOrder: number;
+ readonly itemStackingOrder: number;
+}, label: string): void {
+ assertRankingTextStyle(input.text, `${label}.text`);
+ assertRankingMotionStyle(input.motion, `${label}.motion`);
+ positive(input.iconSizePx, `${label}.iconSizePx`);
+ nonNegative(input.iconRadiusPx, `${label}.iconRadiusPx`);
+ assert(input.iconFit === "contain" || input.iconFit === "cover", `${label}.iconFit is invalid.`);
+ stacking(input.boardStackingOrder, `${label}.boardStackingOrder`);
+ stacking(input.itemStackingOrder, `${label}.itemStackingOrder`);
+}
+
+export function assertTierBoardStyle(value: TierBoardStyle): void {
+ assert(value.contract === "svml.tier-board-style@1", "Unsupported TierBoardStyle contract.");
+ assertCommonStyle(value, "TierBoardStyle");
+ assertRankingBoardPaint(value.board, "TierBoardStyle.board");
+ assert(value.rows.length > 0, "TierBoardStyle.rows is empty.");
+ const rows = new Set<string>();
+ for (const [index, row] of value.rows.entries()) {
+ identity(row.id, `TierBoardStyle.rows.${index}.id`);
+ assert(!rows.has(row.id), `TierBoardStyle repeats row ${row.id}.`);
+ rows.add(row.id);
+ assert(row.label.trim().length > 0, `TierBoardStyle.rows.${index}.label is empty.`);
+ color(row.color, `TierBoardStyle.rows.${index}.color`);
+ }
+ for (const [name, numberValue] of Object.entries({
+ labelWidthPx: value.labelWidthPx, paddingPx: value.paddingPx, rowHeightPx: value.rowHeightPx,
+ rowGapPx: value.rowGapPx, cellGapPx: value.cellGapPx, stageSizePx: value.stageSizePx,
+ })) nonNegative(numberValue, `TierBoardStyle.${name}`);
+ assert(value.labelWidthPx > 0 && value.rowHeightPx > 0 && value.stageSizePx > 0,
+ "TierBoardStyle positive geometry is invalid.");
+ for (const [name, coordinate] of Object.entries(value.stagePoint)) {
+ assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `TierBoardStyle.stagePoint.${name} is invalid.`);
+ }
+ stacking(value.stageStackingOrder, "TierBoardStyle.stageStackingOrder");
+}
+
+export function assertColumnStyle(value: ColumnStyle): void {
+ assert(value.contract === "svml.column-style@1", "Unsupported ColumnStyle contract.");
+ assertCommonStyle(value, "ColumnStyle");
+ assertRankingBoardPaint(value.board, "ColumnStyle.board");
+ assert(value.rankColors.length > 0, "ColumnStyle.rankColors is empty.");
+ value.rankColors.forEach((item, index) => color(item, `ColumnStyle.rankColors.${index}`));
+ for (const [name, numberValue] of Object.entries({
+ paddingPx: value.paddingPx, rowHeightPx: value.rowHeightPx, rowGapPx: value.rowGapPx, stageSizePx: value.stageSizePx,
+ })) nonNegative(numberValue, `ColumnStyle.${name}`);
+ assert(value.rowHeightPx > 0 && value.stageSizePx > 0, "ColumnStyle positive geometry is invalid.");
+ for (const [name, coordinate] of Object.entries(value.stagePoint)) {
+ assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `ColumnStyle.stagePoint.${name} is invalid.`);
+ }
+ stacking(value.stageStackingOrder, "ColumnStyle.stageStackingOrder");
+}
+
+export function assertTopThreeStyle(value: TopThreeStyle): void {
+ assert(value.contract === "svml.top-three-style@1", "Unsupported TopThreeStyle contract.");
+ assertCommonStyle(value, "TopThreeStyle");
+ assert(value.slotColors.length >= 3, "TopThreeStyle requires three slot colors.");
+ value.slotColors.forEach((item, index) => color(item, `TopThreeStyle.slotColors.${index}`));
+ for (const [name, coordinate] of [["centerX", value.centerX], ["baselineY", value.baselineY]] as const) {
+ assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `TopThreeStyle.${name} is invalid.`);
+ }
+ positive(value.slotGapPx, "TopThreeStyle.slotGapPx");
+ nonNegative(value.ringWidthPx, "TopThreeStyle.ringWidthPx");
+ nonNegative(value.labelGapPx, "TopThreeStyle.labelGapPx");
+}
+
+export function assertTypewriterListStyle(value: TypewriterListStyle): void {
+ assert(value.contract === "svml.typewriter-list-style@1", "Unsupported TypewriterListStyle contract.");
+ assertRankingBoardPaint(value.paper, "TypewriterListStyle.paper");
+ assertRankingTextStyle(value.title, "TypewriterListStyle.title");
+ assertRankingTextStyle(value.item, "TypewriterListStyle.item");
+ color(value.emphasisColor, "TypewriterListStyle.emphasisColor");
+ color(value.winnerColor, "TypewriterListStyle.winnerColor");
+ nonNegative(value.paddingPx, "TypewriterListStyle.paddingPx");
+ nonNegative(value.rowGapPx, "TypewriterListStyle.rowGapPx");
+ nonNegative(value.titleGapPx, "TypewriterListStyle.titleGapPx");
+ finite(value.rotationDeg, "TypewriterListStyle.rotationDeg");
+ integer(value.framesPerGrapheme, "TypewriterListStyle.framesPerGrapheme", 1);
+ integer(value.winnerFrames, "TypewriterListStyle.winnerFrames", 1);
+ stacking(value.boardStackingOrder, "TypewriterListStyle.boardStackingOrder");
+ stacking(value.itemStackingOrder, "TypewriterListStyle.itemStackingOrder");
+}
+
+export function assertRankingItemSpec(value: RankingItemSpec): void {
+ identity(value.id, "RankingItemSpec.id");
+ if (value.variant === "tier-board") {
+ assert(value.contract === "svml.tier-board-item-spec@1", "TierBoardItemSpec contract is invalid.");
+ identity(value.tier, `TierBoardItemSpec.${value.id}.tier`);
+ assert(value.entry === "direct" || value.entry === "stage", `TierBoardItemSpec.${value.id}.entry is invalid.`);
+ } else if (value.variant === "column") {
+ assert(value.contract === "svml.column-item-spec@1", "ColumnItemSpec contract is invalid.");
+ assert(value.label.trim().length > 0, `ColumnItemSpec.${value.id}.label is empty.`);
+ } else if (value.variant === "top-three") {
+ assert(value.contract === "svml.top-three-item-spec@1", "TopThreeItemSpec contract is invalid.");
+ assert(value.label.trim().length > 0, `TopThreeItemSpec.${value.id}.label is empty.`);
+ } else {
+ assert(value.variant === "typewriter-list" && value.contract === "svml.typewriter-item-spec@1",
+ "TypewriterItemSpec contract is invalid.");
+ assert(value.text.length > 0, `TypewriterItemSpec.${value.id}.text is empty.`);
+ assert(typeof value.winner === "boolean", `TypewriterItemSpec.${value.id}.winner is invalid.`);
+ if (value.emphasis !== undefined) {
+ integer(value.emphasis.start, `TypewriterItemSpec.${value.id}.emphasis.start`);
+ integer(value.emphasis.endExclusive, `TypewriterItemSpec.${value.id}.emphasis.endExclusive`, 1);
+ assert(value.emphasis.endExclusive > value.emphasis.start,
+ `TypewriterItemSpec.${value.id}.emphasis is empty.`);
+ }
+ }
+ if (value.stackingOrder !== undefined) stacking(value.stackingOrder, `RankingItemSpec.${value.id}.stackingOrder`);
+}
+
+export function createRankingItemSpecSet(header: RankingHeader): RankingItemSpecSet {
+ assertRankingHeader(header);
+ return { contract: "svml.ranking-item-spec-set@1", variant: header.variant, items: [] };
+}
+
+export function assertRankingItemSpecSet(value: RankingItemSpecSet): void {
+ assert(value.contract === "svml.ranking-item-spec-set@1", "Unsupported RankingItemSpecSet contract.");
+ assert(["tier-board", "column", "top-three", "typewriter-list"].includes(value.variant),
+ "RankingItemSpecSet.variant is invalid.");
+ const ids = new Set<string>();
+ for (const item of value.items) {
+ assertRankingItemSpec(item);
+ assert(item.variant === value.variant, "RankingItemSpecSet mixes component variants.");
+ assert(!ids.has(item.id), `RankingItemSpecSet repeats ${item.id}.`);
+ ids.add(item.id);
+ }
+}
+
+export function appendRankingItemSpec(set: RankingItemSpecSet, spec: RankingItemSpec): RankingItemSpecSet {
+ assertRankingItemSpecSet(set);
+ assertRankingItemSpec(spec);
+ assert(spec.variant === set.variant, "Ranking Item variant does not match its component.");
+ const result: RankingItemSpecSet = { ...set, items: [...set.items, structuredClone(spec)] };
+ assertRankingItemSpecSet(result);
+ return canonicalize(result) as unknown as RankingItemSpecSet;
+}
+
+export function buildRankingSchedule(input: {
+ readonly header: RankingHeader;
+ readonly items: RankingItemSpecSet;
+ readonly map: CompleteSemanticMap;
+ readonly space: ProgramSpace;
+ readonly outer: NarrativeSelectionRef;
+ readonly triggers: NarrativeMomentRef;
+ readonly terminal: NarrativeMomentRef;
+}): RankingSchedule {
+ assertRankingHeader(input.header);
+ assertRankingItemSpecSet(input.items);
+ assert(input.items.variant === input.header.variant, "Ranking schedule variant disagrees with its item set.");
+ assert(input.items.items.length > 0, "Ranking requires at least one Item.");
+ assertProgramSpaceIdentity(input.space);
+ const outer = locateSelectionOccurrences(input.map, input.outer, input.space);
+ assert(outer.length === 1, `Ranking outer Selection requires exactly one occurrence; received ${outer.length}.`);
+ const terminal = locateMomentOccurrences(input.map, input.terminal, input.space);
+ assert(terminal.length === 1, `Ranking terminal Moment requires exactly one occurrence; received ${terminal.length}.`);
+ const triggers = locateMomentOccurrences(input.map, input.triggers, input.space);
+ assert(triggers.length > 0, "Ranking trigger Moment requires at least one occurrence.");
+ assert(triggers.length === input.items.items.length,
+ `Ranking trigger/item cardinality differs: ${triggers.length} triggers for ${input.items.items.length} Items.`);
+ const resolved = resolveTriggeredSchedule({
+ outer: { startFrame: outer[0]!.start.frame, endFrameExclusive: outer[0]!.end.frame },
+ terminalFrame: terminal[0]!.cue.frame,
+ triggers: triggers.map((item) => ({ id: item.id, frame: item.cue.frame })),
+ });
+ const entries = input.items.items.map((item, index) => {
+ const exclusive = resolved.exclusive[index]!;
+ const cumulative = resolved.cumulative[index]!;
+ return {
+ itemId: item.id,
+ triggerOccurrenceId: exclusive.triggerId,
+ triggerFrame: exclusive.span.startFrame,
+ stage: { ...exclusive.span },
+ cumulative: { ...cumulative.span },
+ settled: { startFrame: exclusive.span.endFrameExclusive, endFrameExclusive: resolved.outer.endFrameExclusive },
+ };
+ });
+ const result: RankingSchedule = {
+ contract: "svml.ranking-schedule@1",
+ id: input.header.id,
+ variant: input.header.variant,
+ outer: { ...resolved.outer },
+ terminalFrame: resolved.terminalFrame,
+ entries,
+ };
+ assertRankingSchedule(result, input.space);
+ return canonicalize(result) as unknown as RankingSchedule;
+}
+
+export function assertRankingSchedule(value: RankingSchedule, space?: ProgramSpace): void {
+ assert(value.contract === "svml.ranking-schedule@1", "Unsupported RankingSchedule contract.");
+ identity(value.id, "RankingSchedule.id");
+ assert(["tier-board", "column", "top-three", "typewriter-list"].includes(value.variant),
+ "RankingSchedule.variant is invalid.");
+ frame(value.outer.startFrame, "RankingSchedule.outer.startFrame");
+ frame(value.outer.endFrameExclusive, "RankingSchedule.outer.endFrameExclusive");
+ assert(value.outer.endFrameExclusive > value.outer.startFrame, "RankingSchedule.outer is empty.");
+ frame(value.terminalFrame, "RankingSchedule.terminalFrame");
+ assert(value.terminalFrame <= value.outer.endFrameExclusive, "RankingSchedule terminal exceeds outer end.");
+ assert(value.entries.length > 0, "RankingSchedule.entries is empty.");
+ const ids = new Set<string>();
+ let previous = value.outer.startFrame - 1;
+ for (const [index, entry] of value.entries.entries()) {
+ identity(entry.itemId, `RankingSchedule.entries.${index}.itemId`);
+ assert(!ids.has(entry.itemId), `RankingSchedule repeats ${entry.itemId}.`);
+ ids.add(entry.itemId);
+ assert(entry.triggerOccurrenceId.length > 0, `RankingSchedule.entries.${index} has no occurrence identity.`);
+ frame(entry.triggerFrame, `RankingSchedule.entries.${index}.triggerFrame`);
+ assert(entry.triggerFrame > previous, "RankingSchedule trigger frames are not strictly increasing.");
+ previous = entry.triggerFrame;
+ assert(entry.stage.startFrame === entry.triggerFrame
+ && entry.stage.endFrameExclusive === (value.entries[index + 1]?.triggerFrame ?? value.terminalFrame),
+ `RankingSchedule.entries.${index}.stage is inconsistent.`);
+ assert(entry.cumulative.startFrame === entry.triggerFrame
+ && entry.cumulative.endFrameExclusive === value.outer.endFrameExclusive,
+ `RankingSchedule.entries.${index}.cumulative is inconsistent.`);
+ assert(entry.settled.startFrame === entry.stage.endFrameExclusive
+ && entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
+ `RankingSchedule.entries.${index}.settled is inconsistent.`);
+ }
+ assert(value.entries[0]!.triggerFrame >= value.outer.startFrame, "RankingSchedule starts before its outer window.");
+ assert(value.entries.at(-1)!.stage.endFrameExclusive === value.terminalFrame,
+ "RankingSchedule final stage does not end at terminal.");
+ if (space !== undefined) {
+ assertProgramSpaceIdentity(space);
+ assert(value.outer.endFrameExclusive <= programSpaceFrameCount(space), "RankingSchedule exceeds ProgramSpace.");
+ }
+}
+
+function emptySet<T extends { readonly contract: string; readonly items: readonly unknown[] }>(contract: T["contract"]): T {
+ return { contract, items: [] } as unknown as T;
+}
+
+export const createTierBoardItemSet = (): TierBoardItemSet => emptySet("svml.tier-board-item-set@1");
+export const createColumnItemSet = (): ColumnItemSet => emptySet("svml.column-item-set@1");
+export const createTopThreeItemSet = (): TopThreeItemSet => emptySet("svml.top-three-item-set@1");
+export const createTypewriterItemSet = (): TypewriterItemSet => emptySet("svml.typewriter-item-set@1");
+
+function ensureNew(items: readonly { readonly id: string }[], id: string): void {
+ assert(!items.some((item) => item.id === id), `Ranking Item ${id} is duplicated.`);
+}
+
+export function appendTierBoardItem(set: TierBoardItemSet, spec: TierBoardItemSpec, icon: TierBoardItem["icon"]): TierBoardItemSet {
+ assert(set.contract === "svml.tier-board-item-set@1", "TierBoardItemSet is invalid.");
+ assertRankingItemSpec(spec);
+ assertBlobImage(icon, `TierBoardItem.${spec.id}.icon`);
+ ensureNew(set.items, spec.id);
+ return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), icon: structuredClone(icon) }] }) as unknown as TierBoardItemSet;
+}
+
+export function appendColumnItem(set: ColumnItemSet, spec: ColumnItemSpec, icon?: ColumnItem["icon"]): ColumnItemSet {
+ assert(set.contract === "svml.column-item-set@1", "ColumnItemSet is invalid.");
+ assertRankingItemSpec(spec);
+ if (icon !== undefined) assertBlobImage(icon, `ColumnItem.${spec.id}.icon`);
+ ensureNew(set.items, spec.id);
+ return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), ...(icon === undefined ? {} : { icon: structuredClone(icon) }) }] }) as unknown as ColumnItemSet;
+}
+
+export function appendTopThreeItem(set: TopThreeItemSet, spec: TopThreeItemSpec, icon?: TopThreeItem["icon"]): TopThreeItemSet {
+ assert(set.contract === "svml.top-three-item-set@1", "TopThreeItemSet is invalid.");
+ assertRankingItemSpec(spec);
+ if (icon !== undefined) assertBlobImage(icon, `TopThreeItem.${spec.id}.icon`);
+ ensureNew(set.items, spec.id);
+ return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), ...(icon === undefined ? {} : { icon: structuredClone(icon) }) }] }) as unknown as TopThreeItemSet;
+}
+
+export function appendTypewriterItem(set: TypewriterItemSet, spec: TypewriterItemSpec): TypewriterItemSet {
+ assert(set.contract === "svml.typewriter-item-set@1", "TypewriterItemSet is invalid.");
+ assertRankingItemSpec(spec);
+ ensureNew(set.items, spec.id);
+ return canonicalize({ ...set, items: [...set.items, structuredClone(spec)] }) as unknown as TypewriterItemSet;
+}
+
+function idsEqual(schedule: RankingSchedule, items: readonly { readonly id: string }[]): void {
+ assert(schedule.entries.length === items.length, "Ranking Program item count differs from its Schedule.");
+ for (const [index, item] of items.entries()) {
+ assert(schedule.entries[index]?.itemId === item.id, "Ranking Program item order differs from its Schedule.");
+ }
+}
+
+function validateStageDurations(schedule: RankingSchedule, style: RankingMotionStyle, needsMove: (index: number) => boolean): void {
+ for (const [index, entry] of schedule.entries.entries()) {
+ const duration = entry.stage.endFrameExclusive - entry.stage.startFrame;
+ const required = style.appearFrames + (needsMove(index) ? style.moveFrames : 0);
+ assert(required <= duration,
+ `Ranking Item ${entry.itemId} stage has ${duration} frames but requires ${required} animation frames.`);
+ }
+}
+
+export function buildTierBoardProgram(header: RankingHeader, frameValue: import("@narratage/spatial").SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {
+ assert(header.variant === "tier-board" && schedule.variant === "tier-board", "TierBoard variant is inconsistent.");
+ assertSpatialFrame(frameValue);
+ assertTierBoardStyle(style);
+ idsEqual(schedule, set.items);
+ const rows = new Set(style.rows.map((row) => row.id));
+ for (const item of set.items) assert(rows.has(item.tier), `TierBoard Item ${item.id} references unknown tier ${item.tier}.`);
+ validateStageDurations(schedule, style.motion, (index) => set.items[index]?.entry === "stage");
+ const result: TierBoardProgram = { contract: "svml.tier-board-program@1", id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items: structuredClone(set.items) };
+ assertTierBoardProgram(result);
+ return canonicalize(result) as unknown as TierBoardProgram;
+}
+
+export function buildColumnProgram(header: RankingHeader, frameValue: import("@narratage/spatial").SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
+ assert(header.variant === "column" && schedule.variant === "column", "Column variant is inconsistent.");
+ assertSpatialFrame(frameValue);
+ assertColumnStyle(style);
+ idsEqual(schedule, set.items);
+ validateStageDurations(schedule, style.motion, () => true);
+ const result: ColumnProgram = { contract: "svml.column-program@1", id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items: structuredClone(set.items) };
+ assertColumnProgram(result);
+ return canonicalize(result) as unknown as ColumnProgram;
+}
+
+export function buildTopThreeProgram(header: RankingHeader, frameValue: import("@narratage/spatial").SpatialFrame, schedule: RankingSchedule, style: TopThreeStyle, set: TopThreeItemSet): TopThreeProgram {
+ assert(header.variant === "top-three" && schedule.variant === "top-three", "TopThree variant is inconsistent.");
+ assertSpatialFrame(frameValue);
+ assertTopThreeStyle(style);
+ idsEqual(schedule, set.items);
+ assert(set.items.length <= 3, "TopThree accepts at most three Items.");
+ validateStageDurations(schedule, style.motion, () => false);
+ const result: TopThreeProgram = { contract: "svml.top-three-program@1", id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items: structuredClone(set.items) };
+ assertTopThreeProgram(result);
+ return canonicalize(result) as unknown as TopThreeProgram;
+}
+
+export function graphemes(text: string): string[] {
+ return [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)].map((value) => value.segment);
+}
+
+export function buildTypewriterListProgram(header: RankingHeader, title: string, frameValue: import("@narratage/spatial").SpatialFrame, schedule: RankingSchedule, style: TypewriterListStyle, set: TypewriterItemSet): TypewriterListProgram {
+ assert(header.variant === "typewriter-list" && schedule.variant === "typewriter-list", "TypewriterList variant is inconsistent.");
+ assert(title.trim().length > 0, "TypewriterList title is empty.");
+ assertSpatialFrame(frameValue);
+ assertTypewriterListStyle(style);
+ idsEqual(schedule, set.items);
+ for (const [index, item] of set.items.entries()) {
+ const count = graphemes(item.text).length;
+ if (item.emphasis !== undefined) assert(item.emphasis.endExclusive <= count,
+ `Typewriter Item ${item.id} emphasis exceeds its grapheme count.`);
+ const duration = schedule.entries[index]!.stage.endFrameExclusive - schedule.entries[index]!.stage.startFrame;
+ const required = count * style.framesPerGrapheme + (item.winner ? style.winnerFrames : 0);
+ assert(required <= duration,
+ `Typewriter Item ${item.id} stage has ${duration} frames but typing${item.winner ? " and winner mark" : ""} requires ${required}.`);
+ }
+ const result: TypewriterListProgram = { contract: "svml.typewriter-list-program@1", id: header.id, title, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items: structuredClone(set.items) };
+ assertTypewriterListProgram(result);
+ return canonicalize(result) as unknown as TypewriterListProgram;
+}
+
+export function assertTierBoardProgram(value: TierBoardProgram): void {
+ assert(value.contract === "svml.tier-board-program@1", "Unsupported TierBoardProgram contract.");
+ assertRankingSchedule(value.schedule);
+ assert(value.schedule.variant === "tier-board", "TierBoardProgram Schedule variant is invalid.");
+ assertSpatialFrame(value.frame);
+ assertTierBoardStyle(value.style);
+ idsEqual(value.schedule, value.items);
+ value.items.forEach((item) => { assertRankingItemSpec(item); assertBlobImage(item.icon, `TierBoardItem.${item.id}.icon`); });
+}
+
+export function assertColumnProgram(value: ColumnProgram): void {
+ assert(value.contract === "svml.column-program@1", "Unsupported ColumnProgram contract.");
+ assertRankingSchedule(value.schedule);
+ assert(value.schedule.variant === "column", "ColumnProgram Schedule variant is invalid.");
+ assertSpatialFrame(value.frame);
+ assertColumnStyle(value.style);
+ idsEqual(value.schedule, value.items);
+ value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `ColumnItem.${item.id}.icon`); });
+}
+
+export function assertTopThreeProgram(value: TopThreeProgram): void {
+ assert(value.contract === "svml.top-three-program@1", "Unsupported TopThreeProgram contract.");
+ assertRankingSchedule(value.schedule);
+ assert(value.schedule.variant === "top-three", "TopThreeProgram Schedule variant is invalid.");
+ assertSpatialFrame(value.frame);
+ assertTopThreeStyle(value.style);
+ assert(value.items.length <= 3, "TopThreeProgram exceeds three Items.");
+ idsEqual(value.schedule, value.items);
+ value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `TopThreeItem.${item.id}.icon`); });
+}
+
+export function assertTypewriterListProgram(value: TypewriterListProgram): void {
+ assert(value.contract === "svml.typewriter-list-program@1", "Unsupported TypewriterListProgram contract.");
+ assert(value.title.trim().length > 0, "TypewriterListProgram title is empty.");
+ assertRankingSchedule(value.schedule);
+ assert(value.schedule.variant === "typewriter-list", "TypewriterListProgram Schedule variant is invalid.");
+ assertSpatialFrame(value.frame);
+ assertTypewriterListStyle(value.style);
+ idsEqual(value.schedule, value.items);
+ value.items.forEach(assertRankingItemSpec);
+}
+
+function event(id: string, itemId: string, kind: "appear" | "move", eventFrame: number): RankingSoundEvent {
+ return { id: `${id}:${itemId}:${kind}`, itemId, kind, frame: eventFrame };
+}
+
+function sealEvents(id: string, variant: RankingVariant, events: readonly RankingSoundEvent[]): RankingSoundEventPlan {
+ const value: RankingSoundEventPlan = { contract: "svml.ranking-sound-event-plan@1", id, variant, events };
+ assertRankingSoundEventPlan(value);
+ return canonicalize(value) as unknown as RankingSoundEventPlan;
+}
+
+export function buildTierBoardSoundEvents(schedule: RankingSchedule, style: TierBoardStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
+ assert(schedule.variant === "tier-board" && specs.variant === "tier-board", "TierBoard event inputs disagree.");
+ assertTierBoardStyle(style);
+ idsEqual(schedule, specs.items);
+ const events = schedule.entries.flatMap((entry, index) => {
+ const spec = specs.items[index] as TierBoardItemSpec;
+ return [event(schedule.id, entry.itemId, "appear", entry.triggerFrame),
+ ...(spec.entry === "stage" ? [event(schedule.id, entry.itemId, "move", entry.stage.endFrameExclusive - style.motion.moveFrames)] : [])];
+ });
+ return sealEvents(schedule.id, schedule.variant, events);
+}
+
+export function buildColumnSoundEvents(schedule: RankingSchedule, style: ColumnStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
+ assert(schedule.variant === "column" && specs.variant === "column", "Column event inputs disagree.");
+ assertColumnStyle(style);
+ idsEqual(schedule, specs.items);
+ return sealEvents(schedule.id, schedule.variant, schedule.entries.flatMap((entry) => [
+ event(schedule.id, entry.itemId, "appear", entry.triggerFrame),
+ event(schedule.id, entry.itemId, "move", entry.stage.endFrameExclusive - style.motion.moveFrames),
+ ]));
+}
+
+export function buildTopThreeSoundEvents(schedule: RankingSchedule, style: TopThreeStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
+ assert(schedule.variant === "top-three" && specs.variant === "top-three", "TopThree event inputs disagree.");
+ assertTopThreeStyle(style);
+ idsEqual(schedule, specs.items);
+ return sealEvents(schedule.id, schedule.variant,
+ schedule.entries.map((entry) => event(schedule.id, entry.itemId, "appear", entry.triggerFrame)));
+}
+
+export function buildTypewriterSoundEvents(schedule: RankingSchedule, style: TypewriterListStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
+ assert(schedule.variant === "typewriter-list" && specs.variant === "typewriter-list", "Typewriter event inputs disagree.");
+ assertTypewriterListStyle(style);
+ idsEqual(schedule, specs.items);
+ return sealEvents(schedule.id, schedule.variant, schedule.entries.flatMap((entry, index) => {
+ const spec = specs.items[index] as TypewriterItemSpec;
+ const typed = graphemes(spec.text).length * style.framesPerGrapheme;
+ return [event(schedule.id, entry.itemId, "appear", entry.triggerFrame),
+ ...(spec.winner ? [event(schedule.id, entry.itemId, "move", entry.triggerFrame + typed)] : [])];
+ }));
+}
+
+export function assertRankingSoundEventPlan(value: RankingSoundEventPlan): void {
+ assert(value.contract === "svml.ranking-sound-event-plan@1", "Unsupported RankingSoundEventPlan contract.");
+ identity(value.id, "RankingSoundEventPlan.id");
+ assert(["tier-board", "column", "top-three", "typewriter-list"].includes(value.variant),
+ "RankingSoundEventPlan.variant is invalid.");
+ const ids = new Set<string>();
+ for (const item of value.events) {
+ identity(item.id, "RankingSoundEvent.id");
+ identity(item.itemId, "RankingSoundEvent.itemId");
+ assert(item.kind === "appear" || item.kind === "move", `RankingSoundEvent ${item.id} kind is invalid.`);
+ frame(item.frame, `RankingSoundEvent ${item.id}.frame`);
+ assert(!ids.has(item.id), `RankingSoundEventPlan repeats ${item.id}.`);
+ ids.add(item.id);
+ }
+}
+
+export function createRankingSoundSet(): RankingSoundSet {
+ return { contract: "svml.ranking-sound-set@1" };
+}
+
+export function appendRankingSound(set: RankingSoundSet, kind: "appear" | "move", media: SynchronizedMedia): RankingSoundSet {
+ assert(set.contract === "svml.ranking-sound-set@1", "RankingSoundSet is invalid.");
+ verifySynchronizedMedia(media);
+ assert(media.audio !== undefined, `Ranking ${kind} sound has no normalized audio.`);
+ assert(set[kind] === undefined, `Ranking ${kind} sound is already set.`);
+ return canonicalize({ ...set, [kind]: structuredClone(media) }) as unknown as RankingSoundSet;
+}
diff --git a/packages/ranking/src/style.ts b/packages/ranking/src/style.ts
new file mode 100644
index 00000000..4ac9f01e
--- /dev/null
+++ b/packages/ranking/src/style.ts
@@ -0,0 +1,286 @@
+import {
+ assertFontArtifactRef,
+ assertFontStackRef,
+} from "@narratage/media";
+import type {
+ FontArtifactRef,
+ FontStackRef,
+} from "@narratage/media";
+import { canonicalize } from "@narratage/protocol";
+import type { SvsRecipe } from "@narratage/svs";
+
+import {
+ assertColumnStyle,
+ assertRankingSoundStyle,
+ assertTierBoardStyle,
+ assertTopThreeStyle,
+ assertTypewriterListStyle,
+} from "./schedule.js";
+import type {
+ ColumnStyle,
+ RankingBoardPaint,
+ RankingMotionStyle,
+ RankingSoundStyle,
+ RankingTextStyle,
+ TierBoardStyle,
+ TierRowStyle,
+ TopThreeStyle,
+ TypewriterListStyle,
+} from "./types.js";
+
+const COMMON_KEYS = [
+ "font-size", "font-weight", "text-color", "line-height",
+ "appear-frames", "move-frames", "motion-easing",
+ "board-background", "board-border-color", "board-border-width", "board-radius",
+ "board-shadow-x", "board-shadow-y", "board-shadow-blur", "board-shadow-spread", "board-shadow-color",
+ "board-stack", "item-stack", "stage-stack",
+ "appear-gain", "move-gain", "sound-fade-frames",
+] as const;
+
+const TIER_KEYS = [
+ ...COMMON_KEYS,
+ "rows", "label-width", "padding", "row-height", "row-gap", "cell-gap",
+ "icon-size", "icon-radius", "icon-fit", "stage-x", "stage-y", "stage-size",
+] as const;
+
+const COLUMN_KEYS = [
+ ...COMMON_KEYS,
+ "rank-colors", "padding", "row-height", "row-gap", "icon-size", "icon-radius", "icon-fit",
+ "stage-x", "stage-y", "stage-size",
+] as const;
+
+const TOP_KEYS = [
+ ...COMMON_KEYS,
+ "slot-colors", "center-x", "baseline-y", "slot-gap", "icon-size", "icon-radius", "icon-fit",
+ "ring-width", "label-gap",
+] as const;
+
+const TYPEWRITER_KEYS = [
+ ...COMMON_KEYS,
+ "title-font-size", "title-font-weight", "title-color", "title-line-height",
+ "item-font-size", "item-font-weight", "item-color", "item-line-height",
+ "emphasis-color", "winner-color", "padding", "row-gap", "title-gap", "rotation",
+ "frames-per-grapheme", "winner-frames",
+] as const;
+
+function fail(recipe: SvsRecipe, message: string): never {
+ throw new Error(`Ranking Recipe ${recipe.path} ${message}`);
+}
+
+function known(recipe: SvsRecipe, allowed: readonly string[]): void {
+ const set = new Set(allowed);
+ const unknown = Object.keys(recipe.properties).filter((key) => !set.has(key));
+ if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+}
+
+function number(recipe: SvsRecipe, name: string, fallback: number): number {
+ const value = recipe.properties[name];
+ if (value === undefined) return fallback;
+ if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
+ return value;
+}
+
+function integer(recipe: SvsRecipe, name: string, fallback: number): number {
+ const value = number(recipe, name, fallback);
+ if (!Number.isSafeInteger(value)) fail(recipe, `${name} must be an integer.`);
+ return value;
+}
+
+function text(recipe: SvsRecipe, name: string, fallback: string): string {
+ const value = recipe.properties[name];
+ if (value === undefined) return fallback;
+ if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
+ return value.trim();
+}
+
+function oneOf<T extends string>(recipe: SvsRecipe, name: string, values: readonly T[], fallback: T): T {
+ const value = text(recipe, name, fallback);
+ if (!values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
+ return value as T;
+}
+
+function exactFonts(value: FontStackRef | FontArtifactRef): FontArtifactRef[] {
+ if (value.contract === "svml.font-stack@1") {
+ assertFontStackRef(value, "Ranking font");
+ return [...structuredClone(value.faces)];
+ }
+ assertFontArtifactRef(value, "Ranking font");
+ return [structuredClone(value)];
+}
+
+function typography(
+ recipe: SvsRecipe,
+ fonts: readonly FontArtifactRef[],
+ prefix: "" | "title-" | "item-" = "",
+ defaults: { readonly size: number; readonly weight: number; readonly color: string; readonly lineHeight: number } = {
+ size: 28, weight: 700, color: "#ffffff", lineHeight: 1.15,
+ },
+): RankingTextStyle {
+ return {
+ fonts: structuredClone(fonts),
+ sizePx: number(recipe, `${prefix}font-size`, defaults.size),
+ weight: integer(recipe, `${prefix}font-weight`, defaults.weight),
+ color: text(recipe, `${prefix}${prefix.length === 0 ? "text-color" : "color"}`, defaults.color),
+ lineHeight: number(recipe, `${prefix}line-height`, defaults.lineHeight),
+ };
+}
+
+function board(recipe: SvsRecipe): RankingBoardPaint {
+ return {
+ background: text(recipe, "board-background", "#151821"),
+ borderColor: text(recipe, "board-border-color", "#ffffff33"),
+ borderWidthPx: number(recipe, "board-border-width", 1),
+ radiusPx: number(recipe, "board-radius", 18),
+ shadow: {
+ offsetX: number(recipe, "board-shadow-x", 0),
+ offsetY: number(recipe, "board-shadow-y", 10),
+ blurPx: number(recipe, "board-shadow-blur", 24),
+ spreadPx: number(recipe, "board-shadow-spread", 0),
+ color: text(recipe, "board-shadow-color", "#00000066"),
+ },
+ };
+}
+
+function motion(recipe: SvsRecipe): RankingMotionStyle {
+ return {
+ appearFrames: integer(recipe, "appear-frames", 6),
+ moveFrames: integer(recipe, "move-frames", 8),
+ easing: oneOf(recipe, "motion-easing", ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
+ };
+}
+
+function sound(recipe: SvsRecipe): RankingSoundStyle {
+ const value: RankingSoundStyle = {
+ contract: "svml.ranking-sound-style@1",
+ appearGain: number(recipe, "appear-gain", 1),
+ moveGain: number(recipe, "move-gain", 1),
+ fadeFrames: integer(recipe, "sound-fade-frames", 0),
+ };
+ assertRankingSoundStyle(value);
+ return canonicalize(value) as unknown as RankingSoundStyle;
+}
+
+function rowList(recipe: SvsRecipe): TierRowStyle[] {
+ const raw = text(recipe, "rows", "s:S:#ef4444|a:A:#f59e0b|b:B:#22c55e|c:C:#3b82f6");
+ return raw.split("|").map((item, index) => {
+ const [id, label, color] = item.split(":").map((part) => part.trim());
+ if (!id || !label || !color) fail(recipe, `rows entry ${index + 1} must be id:label:color.`);
+ return { id, label, color };
+ });
+}
+
+function colorList(recipe: SvsRecipe, name: string, fallback: string): string[] {
+ const result = text(recipe, name, fallback).split("|").map((value) => value.trim()).filter(Boolean);
+ if (result.length === 0) fail(recipe, `${name} is empty.`);
+ return result;
+}
+
+export function decodeTierBoardStyle(
+ recipe: SvsRecipe,
+ font: FontStackRef | FontArtifactRef,
+): { readonly style: TierBoardStyle; readonly sound: RankingSoundStyle } {
+ known(recipe, TIER_KEYS);
+ const fonts = exactFonts(font);
+ const style: TierBoardStyle = {
+ contract: "svml.tier-board-style@1",
+ rows: rowList(recipe),
+ board: board(recipe),
+ text: typography(recipe, fonts),
+ labelWidthPx: number(recipe, "label-width", 72),
+ paddingPx: number(recipe, "padding", 18),
+ rowHeightPx: number(recipe, "row-height", 92),
+ rowGapPx: number(recipe, "row-gap", 10),
+ cellGapPx: number(recipe, "cell-gap", 12),
+ iconSizePx: number(recipe, "icon-size", 72),
+ iconRadiusPx: number(recipe, "icon-radius", 12),
+ iconFit: oneOf(recipe, "icon-fit", ["contain", "cover"] as const, "cover"),
+ stagePoint: { x: number(recipe, "stage-x", 0.5), y: number(recipe, "stage-y", 0.23) },
+ stageSizePx: number(recipe, "stage-size", 108),
+ motion: motion(recipe),
+ boardStackingOrder: integer(recipe, "board-stack", 20),
+ stageStackingOrder: integer(recipe, "stage-stack", 25),
+ itemStackingOrder: integer(recipe, "item-stack", 30),
+ };
+ assertTierBoardStyle(style);
+ return { style: canonicalize(style) as unknown as TierBoardStyle, sound: sound(recipe) };
+}
+
+export function decodeColumnStyle(
+ recipe: SvsRecipe,
+ font: FontStackRef | FontArtifactRef,
+): { readonly style: ColumnStyle; readonly sound: RankingSoundStyle } {
+ known(recipe, COLUMN_KEYS);
+ const fonts = exactFonts(font);
+ const style: ColumnStyle = {
+ contract: "svml.column-style@1",
+ board: board(recipe),
+ text: typography(recipe, fonts),
+ rankColors: colorList(recipe, "rank-colors", "#facc15|#d1d5db|#fb923c|#60a5fa|#a78bfa"),
+ paddingPx: number(recipe, "padding", 18),
+ rowHeightPx: number(recipe, "row-height", 74),
+ rowGapPx: number(recipe, "row-gap", 10),
+ iconSizePx: number(recipe, "icon-size", 58),
+ iconRadiusPx: number(recipe, "icon-radius", 10),
+ iconFit: oneOf(recipe, "icon-fit", ["contain", "cover"] as const, "cover"),
+ stagePoint: { x: number(recipe, "stage-x", 0.5), y: number(recipe, "stage-y", 0.24) },
+ stageSizePx: number(recipe, "stage-size", 132),
+ motion: motion(recipe),
+ boardStackingOrder: integer(recipe, "board-stack", 20),
+ stageStackingOrder: integer(recipe, "stage-stack", 25),
+ itemStackingOrder: integer(recipe, "item-stack", 30),
+ };
+ assertColumnStyle(style);
+ return { style: canonicalize(style) as unknown as ColumnStyle, sound: sound(recipe) };
+}
+
+export function decodeTopThreeStyle(
+ recipe: SvsRecipe,
+ font: FontStackRef | FontArtifactRef,
+): { readonly style: TopThreeStyle; readonly sound: RankingSoundStyle } {
+ known(recipe, TOP_KEYS);
+ const fonts = exactFonts(font);
+ const style: TopThreeStyle = {
+ contract: "svml.top-three-style@1",
+ text: typography(recipe, fonts),
+ slotColors: colorList(recipe, "slot-colors", "#facc15|#d1d5db|#fb923c"),
+ centerX: number(recipe, "center-x", 0.5),
+ baselineY: number(recipe, "baseline-y", 0.55),
+ slotGapPx: number(recipe, "slot-gap", 24),
+ iconSizePx: number(recipe, "icon-size", 104),
+ iconRadiusPx: number(recipe, "icon-radius", 52),
+ iconFit: oneOf(recipe, "icon-fit", ["contain", "cover"] as const, "cover"),
+ ringWidthPx: number(recipe, "ring-width", 5),
+ labelGapPx: number(recipe, "label-gap", 12),
+ motion: motion(recipe),
+ boardStackingOrder: integer(recipe, "board-stack", 20),
+ itemStackingOrder: integer(recipe, "item-stack", 30),
+ };
+ assertTopThreeStyle(style);
+ return { style: canonicalize(style) as unknown as TopThreeStyle, sound: sound(recipe) };
+}
+
+export function decodeTypewriterListStyle(
+ recipe: SvsRecipe,
+ font: FontStackRef | FontArtifactRef,
+): { readonly style: TypewriterListStyle; readonly sound: RankingSoundStyle } {
+ known(recipe, TYPEWRITER_KEYS);
+ const fonts = exactFonts(font);
+ const style: TypewriterListStyle = {
+ contract: "svml.typewriter-list-style@1",
+ paper: board(recipe),
+ title: typography(recipe, fonts, "title-", { size: 34, weight: 800, color: "#111827", lineHeight: 1.1 }),
+ item: typography(recipe, fonts, "item-", { size: 26, weight: 600, color: "#1f2937", lineHeight: 1.2 }),
+ emphasisColor: text(recipe, "emphasis-color", "#dc2626"),
+ winnerColor: text(recipe, "winner-color", "#eab308"),
+ paddingPx: number(recipe, "padding", 28),
+ rowGapPx: number(recipe, "row-gap", 16),
+ titleGapPx: number(recipe, "title-gap", 22),
+ rotationDeg: number(recipe, "rotation", -1.2),
+ framesPerGrapheme: integer(recipe, "frames-per-grapheme", 2),
+ winnerFrames: integer(recipe, "winner-frames", 5),
+ boardStackingOrder: integer(recipe, "board-stack", 20),
+ itemStackingOrder: integer(recipe, "item-stack", 30),
+ };
+ assertTypewriterListStyle(style);
+ return { style: canonicalize(style) as unknown as TypewriterListStyle, sound: sound(recipe) };
+}
diff --git a/packages/ranking/src/surface.ts b/packages/ranking/src/surface.ts
new file mode 100644
index 00000000..c03f6d0d
--- /dev/null
+++ b/packages/ranking/src/surface.ts
@@ -0,0 +1,319 @@
+import { mediaTypes } from "@narratage/media";
+import type { FontArtifactRef, FontStackRef } from "@narratage/media";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes } from "@narratage/program-space";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { spatialTypes } from "@narratage/spatial";
+import { svsRecipeType } from "@narratage/svs";
+import type { SvsRecipe } from "@narratage/svs";
+import type {
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceRecordDraft,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+
+import { createRankingFragment } from "./fragment.js";
+import type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
+import { rankingTypes } from "./manifest.js";
+import {
+ assertRankingItemSpec,
+ sealRankingHeader,
+} from "./schedule.js";
+import {
+ decodeColumnStyle,
+ decodeTierBoardStyle,
+ decodeTopThreeStyle,
+ decodeTypewriterListStyle,
+} from "./style.js";
+import type {
+ ColumnItemSpec,
+ RankingItemSpec,
+ RankingSoundStyle,
+ RankingVariant,
+ TierBoardItemSpec,
+ TopThreeItemSpec,
+ TypewriterItemSpec,
+} from "./types.js";
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function allowed(element: StructuredElement, names: readonly string[]): void {
+ const permit = new Set(names);
+ const unknown = Object.keys(element.attributes).filter((name) => !permit.has(name));
+ if (unknown.length > 0) throw new Error(`${element.name} has unsupported attributes ${unknown.join(", ")}.`);
+}
+
+function empty(element: StructuredElement): void {
+ if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+ throw new Error(`${element.name} must be empty.`);
+ }
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+ const value = element.attributes[name];
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
+ const value = element.attributes[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function integer(element: StructuredElement, name: string): number | undefined {
+ const source = optionalText(element, name);
+ if (source === undefined) return undefined;
+ const value = Number(source);
+ if (!Number.isSafeInteger(value)) throw new Error(`${element.name}.${name} must be an integer.`);
+ return value;
+}
+
+function boolean(element: StructuredElement, name: string, fallback: boolean): boolean {
+ const source = optionalText(element, name);
+ if (source === undefined) return fallback;
+ if (source === "true") return true;
+ if (source === "false") return false;
+ throw new Error(`${element.name}.${name} must be true or false.`);
+}
+
+function reference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: TypeRef,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const value = resolve(raw.path);
+ if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`);
+ return value;
+}
+
+function oneOfReference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: readonly TypeRef[],
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const value = resolve(raw.path);
+ if (value === undefined || !expected.some((type) => sameType(value.type, type))) throw new Error(`${label} has the wrong Type.`);
+ return value;
+}
+
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+ if (value.record?.value.kind !== "inline") throw new Error(`${label} must resolve during author compilation.`);
+ return value.record.value.value as unknown as T;
+}
+
+function styleSurface<T>(
+ decode: (recipe: SvsRecipe, font: FontArtifactRef | FontStackRef) => { readonly style: T; readonly sound: RankingSoundStyle },
+): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ allowed(element, ["id", "recipe", "font"]);
+ empty(element);
+ const id = text(element, "id");
+ const recipeRef = reference(element.attributes.recipe, `${element.name}.recipe`, svsRecipeType, resolveReference);
+ const fontRef = oneOfReference(element.attributes.font, `${element.name}.font`, [mediaTypes.fontArtifact, mediaTypes.fontStack], resolveReference);
+ const decoded = decode(inline<SvsRecipe>(recipeRef, `${element.name}.recipe`), inline<FontArtifactRef | FontStackRef>(fontRef, `${element.name}.font`));
+ const type = decoded.style !== null && typeof decoded.style === "object" && "contract" in decoded.style
+ ? String((decoded.style as { readonly contract: string }).contract)
+ : "";
+ const styleType = type === "svml.tier-board-style@1" ? rankingTypes.tierStyle
+ : type === "svml.column-style@1" ? rankingTypes.columnStyle
+ : type === "svml.top-three-style@1" ? rankingTypes.topThreeStyle
+ : type === "svml.typewriter-list-style@1" ? rankingTypes.typewriterStyle
+ : undefined;
+ if (styleType === undefined) throw new Error(`${element.name} produced an unknown Ranking Style.`);
+ return {
+ records: [
+ { id, type: styleType, value: { kind: "inline", value: decoded.style as unknown as CanonicalValue }, range: element.range },
+ { id: `${id}.sound`, type: rankingTypes.soundStyle, value: { kind: "inline", value: decoded.sound as unknown as CanonicalValue }, range: element.range },
+ ],
+ components: [], fragments: [],
+ };
+ };
+}
+
+export const decodeTierBoardStyleSurface = styleSurface(decodeTierBoardStyle);
+export const decodeColumnStyleSurface = styleSurface(decodeColumnStyle);
+export const decodeTopThreeStyleSurface = styleSurface(decodeTopThreeStyle);
+export const decodeTypewriterListStyleSurface = styleSurface(decodeTypewriterListStyle);
+
+function localName(element: StructuredElement): string {
+ return element.name.slice(element.name.lastIndexOf(":") + 1);
+}
+
+function plainChildText(element: StructuredElement): string {
+ if (element.children.some((child) => child.kind === "element")) throw new Error(`${element.name} accepts plain text only.`);
+ const value = element.children.map((child) => child.kind === "text" ? child.value : "").join("").trim();
+ if (value.length === 0) throw new Error(`${element.name} text is empty.`);
+ return value;
+}
+
+function itemIdentity(element: StructuredElement, suffix: string): string {
+ return optionalText(element, "id") ?? `${localName(element).replace(/Item$/u, "").toLowerCase()}-${suffix}`;
+}
+
+function itemSpec(element: StructuredElement, variant: RankingVariant, suffix: string): RankingItemSpec {
+ const id = itemIdentity(element, suffix);
+ const stackingOrder = integer(element, "stack");
+ let value: RankingItemSpec;
+ if (variant === "tier-board") {
+ allowed(element, ["id", "tier", "entry", "icon", "stack"]);
+ empty(element);
+ const entry = text(element, "entry", "direct");
+ if (entry !== "direct" && entry !== "stage") throw new Error(`${element.name}.entry must be direct or stage.`);
+ value = {
+ contract: "svml.tier-board-item-spec@1", variant, id, tier: text(element, "tier"), entry,
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies TierBoardItemSpec;
+ } else if (variant === "column") {
+ allowed(element, ["id", "label", "icon", "stack"]);
+ empty(element);
+ value = {
+ contract: "svml.column-item-spec@1", variant, id, label: text(element, "label"),
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies ColumnItemSpec;
+ } else if (variant === "top-three") {
+ allowed(element, ["id", "label", "icon", "stack"]);
+ empty(element);
+ value = {
+ contract: "svml.top-three-item-spec@1", variant, id, label: text(element, "label"),
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies TopThreeItemSpec;
+ } else {
+ allowed(element, ["id", "text", "winner", "emphasis-start", "emphasis-end", "stack"]);
+ const authoredText = optionalText(element, "text");
+ const content = authoredText ?? plainChildText(element);
+ if (authoredText !== undefined) empty(element);
+ const start = integer(element, "emphasis-start");
+ const endExclusive = integer(element, "emphasis-end");
+ if ((start === undefined) !== (endExclusive === undefined)) throw new Error(`${element.name} emphasis requires both emphasis-start and emphasis-end.`);
+ value = {
+ contract: "svml.typewriter-item-spec@1", variant, id, text: content,
+ winner: boolean(element, "winner", false),
+ ...(start === undefined || endExclusive === undefined ? {} : { emphasis: { start, endExclusive } }),
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies TypewriterItemSpec;
+ }
+ assertRankingItemSpec(value);
+ return value;
+}
+
+const variantDefinition = {
+ "tier-board": { tag: "TierItem", style: rankingTypes.tierStyle },
+ column: { tag: "ColumnItem", style: rankingTypes.columnStyle },
+ "top-three": { tag: "TopThreeItem", style: rankingTypes.topThreeStyle },
+ "typewriter-list": { tag: "TypewriterItem", style: rankingTypes.typewriterStyle },
+} as const;
+
+function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ const common = ["id", "map", "space", "frame", "during", "triggers", "terminal", "style", "appear-sound", "move-sound"];
+ allowed(element, variant === "typewriter-list" ? [...common, "title"] : common);
+ const id = text(element, "id");
+ const selected = variantDefinition[variant];
+ const map = reference(element.attributes.map, `${element.name}.map`, semanticMapTypes.complete, resolveReference);
+ const space = reference(element.attributes.space, `${element.name}.space`, programSpaceTypes.programSpace, resolveReference);
+ const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
+ const outer = reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolveReference);
+ const triggers = reference(element.attributes.triggers, `${element.name}.triggers`, narrativeTypes.moment, resolveReference);
+ const terminal = reference(element.attributes.terminal, `${element.name}.terminal`, narrativeTypes.moment, resolveReference);
+ const styleRaw = element.attributes.style;
+ const style = reference(styleRaw, `${element.name}.style`, selected.style, resolveReference);
+ const records: SurfaceRecordDraft[] = [];
+ const headerId = `${id}.header`;
+ records.push({
+ id: headerId, type: rankingTypes.header,
+ value: { kind: "inline", value: sealRankingHeader({ contract: "svml.ranking-header@1", id, variant }) as unknown as CanonicalValue },
+ range: element.range,
+ });
+ const inputs: Record<string, typeof map.ref> = {
+ header: { kind: "record", id: headerId }, map: map.ref, space: space.ref, frame: frame.ref,
+ outer: outer.ref, triggers: triggers.ref, terminal: terminal.ref, style: style.ref,
+ };
+ if (variant === "typewriter-list") {
+ const titleId = `${id}.title`;
+ records.push({ id: titleId, type: rankingTypes.title, value: { kind: "inline", value: { contract: "svml.ranking-title@1", value: text(element, "title") } }, range: element.range });
+ inputs.title = { kind: "record", id: titleId };
+ }
+ const items: RankingFragmentItem[] = [];
+ const itemIds = new Set<string>();
+ let index = 0;
+ let hasStage = false;
+ let hasWinner = false;
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts ${selected.tag} children only.`);
+ continue;
+ }
+ if (localName(child) !== selected.tag) throw new Error(`${element.name} accepts ${selected.tag} children only.`);
+ index += 1;
+ const suffix = String(index).padStart(4, "0");
+ const spec = itemSpec(child, variant, suffix);
+ if (itemIds.has(spec.id)) throw new Error(`${element.name} has duplicate Item id ${spec.id}.`);
+ itemIds.add(spec.id);
+ hasStage ||= spec.variant === "tier-board" && spec.entry === "stage";
+ hasWinner ||= spec.variant === "typewriter-list" && spec.winner;
+ const specId = `${id}.item.${suffix}.spec`;
+ const specName = `item-${suffix}-spec`;
+ records.push({ id: specId, type: rankingTypes.itemSpec, value: { kind: "inline", value: spec as unknown as CanonicalValue }, range: child.range });
+ inputs[specName] = { kind: "record", id: specId };
+ let iconName: string | undefined;
+ if (variant === "tier-board" || child.attributes.icon !== undefined) {
+ const icon = reference(child.attributes.icon, `${child.name}.icon`, mediaTypes.blobArtifact, resolveReference);
+ iconName = `item-${suffix}-icon`;
+ inputs[iconName] = icon.ref;
+ }
+ items.push({ suffix, specName, ...(iconName === undefined ? {} : { iconName }) });
+ }
+ if (items.length === 0) throw new Error(`${element.name} requires at least one ${selected.tag}.`);
+ const sound: RankingFragmentSound = {
+ ...(element.attributes["appear-sound"] === undefined ? {} : { appearName: "appear-sound" }),
+ ...(element.attributes["move-sound"] === undefined ? {} : { moveName: "move-sound" }),
+ };
+ if (sound.moveName !== undefined && variant === "top-three") throw new Error(`${element.name} has no move sound phase.`);
+ if (sound.moveName !== undefined && variant === "tier-board" && !hasStage) throw new Error(`${element.name}.move-sound requires one staged TierItem.`);
+ if (sound.moveName !== undefined && variant === "typewriter-list" && !hasWinner) throw new Error(`${element.name}.move-sound requires one winner TypewriterItem.`);
+ for (const [attribute, inputName] of [["appear-sound", sound.appearName], ["move-sound", sound.moveName]] as const) {
+ if (inputName === undefined) continue;
+ inputs[inputName] = reference(element.attributes[attribute], `${element.name}.${attribute}`, mediaTypes.synchronized, resolveReference).ref;
+ }
+ if (sound.appearName !== undefined || sound.moveName !== undefined) {
+ if (typeof styleRaw !== "object" || styleRaw.kind !== "reference") throw new Error(`${element.name}.style must be a reference.`);
+ const soundStyle = resolveReference(`${styleRaw.path}.sound`);
+ if (soundStyle === undefined || !sameType(soundStyle.type, rankingTypes.soundStyle)) {
+ throw new Error(`${element.name}.style does not expose its Ranking sound style.`);
+ }
+ inputs["sound-style"] = soundStyle.ref;
+ }
+ const fragment = createRankingFragment(variant, items, sound, `@narratage/ranking/surface/${id}@1`);
+ return {
+ records,
+ components: [{
+ id, fragment: fragment.id, inputs,
+ outputs: {
+ schedule: `${id}.schedule`, program: `${id}.program`, visual: `${id}.visual`,
+ ...(sound.appearName === undefined && sound.moveName === undefined ? {} : { audio: `${id}.audio` }),
+ },
+ range: element.range,
+ }],
+ fragments: [fragment],
+ };
+ };
+}
+
+export const decodeTierBoardSurface = rankingSurface("tier-board");
+export const decodeColumnSurface = rankingSurface("column");
+export const decodeTopThreeSurface = rankingSurface("top-three");
+export const decodeTypewriterListSurface = rankingSurface("typewriter-list");
diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.ts
new file mode 100644
index 00000000..bd168a58
--- /dev/null
+++ b/packages/ranking/src/types.ts
@@ -0,0 +1,281 @@
+import type {
+ AudioTrack,
+ FrameSpan,
+ VisualTrack,
+} from "@narratage/composition";
+import type {
+ FontArtifactRef,
+ SynchronizedMedia,
+} from "@narratage/media";
+import type { BlobRef } from "@narratage/protocol";
+import type { SpatialFrame } from "@narratage/spatial";
+
+export type RankingVariant = "tier-board" | "column" | "top-three" | "typewriter-list";
+
+export type RankingHeader = {
+ readonly contract: "svml.ranking-header@1";
+ readonly id: string;
+ readonly variant: RankingVariant;
+};
+
+export type RankingScheduleEntry = {
+ readonly itemId: string;
+ readonly triggerOccurrenceId: string;
+ readonly triggerFrame: number;
+ readonly stage: FrameSpan;
+ readonly cumulative: FrameSpan;
+ readonly settled: FrameSpan;
+};
+
+export type RankingSchedule = {
+ readonly contract: "svml.ranking-schedule@1";
+ readonly id: string;
+ readonly variant: RankingVariant;
+ readonly outer: FrameSpan;
+ readonly terminalFrame: number;
+ readonly entries: readonly RankingScheduleEntry[];
+};
+
+export type RankingTextStyle = {
+ readonly fonts: readonly FontArtifactRef[];
+ readonly sizePx: number;
+ readonly weight: number;
+ readonly color: string;
+ readonly lineHeight: number;
+};
+
+export type RankingBoardPaint = {
+ readonly background: string;
+ readonly borderColor: string;
+ readonly borderWidthPx: number;
+ readonly radiusPx: number;
+ readonly shadow: {
+ readonly offsetX: number;
+ readonly offsetY: number;
+ readonly blurPx: number;
+ readonly spreadPx: number;
+ readonly color: string;
+ };
+};
+
+export type RankingMotionStyle = {
+ readonly appearFrames: number;
+ readonly moveFrames: number;
+ readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+};
+
+export type RankingSoundStyle = {
+ readonly contract: "svml.ranking-sound-style@1";
+ readonly appearGain: number;
+ readonly moveGain: number;
+ readonly fadeFrames: number;
+};
+
+export type TierRowStyle = {
+ readonly id: string;
+ readonly label: string;
+ readonly color: string;
+};
+
+export type TierBoardStyle = {
+ readonly contract: "svml.tier-board-style@1";
+ readonly rows: readonly TierRowStyle[];
+ readonly board: RankingBoardPaint;
+ readonly text: RankingTextStyle;
+ readonly labelWidthPx: number;
+ readonly paddingPx: number;
+ readonly rowHeightPx: number;
+ readonly rowGapPx: number;
+ readonly cellGapPx: number;
+ readonly iconSizePx: number;
+ readonly iconRadiusPx: number;
+ readonly iconFit: "contain" | "cover";
+ readonly stagePoint: { readonly x: number; readonly y: number };
+ readonly stageSizePx: number;
+ readonly motion: RankingMotionStyle;
+ readonly boardStackingOrder: number;
+ readonly stageStackingOrder: number;
+ readonly itemStackingOrder: number;
+};
+
+export type ColumnStyle = {
+ readonly contract: "svml.column-style@1";
+ readonly board: RankingBoardPaint;
+ readonly text: RankingTextStyle;
+ readonly rankColors: readonly string[];
+ readonly paddingPx: number;
+ readonly rowHeightPx: number;
+ readonly rowGapPx: number;
+ readonly iconSizePx: number;
+ readonly iconRadiusPx: number;
+ readonly iconFit: "contain" | "cover";
+ readonly stagePoint: { readonly x: number; readonly y: number };
+ readonly stageSizePx: number;
+ readonly motion: RankingMotionStyle;
+ readonly boardStackingOrder: number;
+ readonly stageStackingOrder: number;
+ readonly itemStackingOrder: number;
+};
+
+export type TopThreeStyle = {
+ readonly contract: "svml.top-three-style@1";
+ readonly text: RankingTextStyle;
+ readonly slotColors: readonly string[];
+ readonly centerX: number;
+ readonly baselineY: number;
+ readonly slotGapPx: number;
+ readonly iconSizePx: number;
+ readonly iconRadiusPx: number;
+ readonly iconFit: "contain" | "cover";
+ readonly ringWidthPx: number;
+ readonly labelGapPx: number;
+ readonly motion: RankingMotionStyle;
+ readonly boardStackingOrder: number;
+ readonly itemStackingOrder: number;
+};
+
+export type TypewriterListStyle = {
+ readonly contract: "svml.typewriter-list-style@1";
+ readonly paper: RankingBoardPaint;
+ readonly title: RankingTextStyle;
+ readonly item: RankingTextStyle;
+ readonly emphasisColor: string;
+ readonly winnerColor: string;
+ readonly paddingPx: number;
+ readonly rowGapPx: number;
+ readonly titleGapPx: number;
+ readonly rotationDeg: number;
+ readonly framesPerGrapheme: number;
+ readonly winnerFrames: number;
+ readonly boardStackingOrder: number;
+ readonly itemStackingOrder: number;
+};
+
+export type TierBoardItemSpec = {
+ readonly contract: "svml.tier-board-item-spec@1";
+ readonly variant: "tier-board";
+ readonly id: string;
+ readonly tier: string;
+ readonly entry: "direct" | "stage";
+ readonly stackingOrder?: number;
+};
+
+export type ColumnItemSpec = {
+ readonly contract: "svml.column-item-spec@1";
+ readonly variant: "column";
+ readonly id: string;
+ readonly label: string;
+ readonly stackingOrder?: number;
+};
+
+export type TopThreeItemSpec = {
+ readonly contract: "svml.top-three-item-spec@1";
+ readonly variant: "top-three";
+ readonly id: string;
+ readonly label: string;
+ readonly stackingOrder?: number;
+};
+
+export type TypewriterItemSpec = {
+ readonly contract: "svml.typewriter-item-spec@1";
+ readonly variant: "typewriter-list";
+ readonly id: string;
+ readonly text: string;
+ readonly emphasis?: { readonly start: number; readonly endExclusive: number };
+ readonly winner: boolean;
+ readonly stackingOrder?: number;
+};
+
+export type RankingItemSpec = TierBoardItemSpec | ColumnItemSpec | TopThreeItemSpec | TypewriterItemSpec;
+
+export type RankingItemSpecSet = {
+ readonly contract: "svml.ranking-item-spec-set@1";
+ readonly variant: RankingVariant;
+ readonly items: readonly RankingItemSpec[];
+};
+
+export type TierBoardItem = TierBoardItemSpec & { readonly icon: BlobRef };
+export type ColumnItem = ColumnItemSpec & { readonly icon?: BlobRef };
+export type TopThreeItem = TopThreeItemSpec & { readonly icon?: BlobRef };
+export type TypewriterItem = TypewriterItemSpec;
+
+export type TierBoardItemSet = {
+ readonly contract: "svml.tier-board-item-set@1";
+ readonly items: readonly TierBoardItem[];
+};
+export type ColumnItemSet = {
+ readonly contract: "svml.column-item-set@1";
+ readonly items: readonly ColumnItem[];
+};
+export type TopThreeItemSet = {
+ readonly contract: "svml.top-three-item-set@1";
+ readonly items: readonly TopThreeItem[];
+};
+export type TypewriterItemSet = {
+ readonly contract: "svml.typewriter-item-set@1";
+ readonly items: readonly TypewriterItem[];
+};
+
+export type TierBoardProgram = {
+ readonly contract: "svml.tier-board-program@1";
+ readonly id: string;
+ readonly frame: SpatialFrame;
+ readonly schedule: RankingSchedule;
+ readonly style: TierBoardStyle;
+ readonly items: readonly TierBoardItem[];
+};
+export type ColumnProgram = {
+ readonly contract: "svml.column-program@1";
+ readonly id: string;
+ readonly frame: SpatialFrame;
+ readonly schedule: RankingSchedule;
+ readonly style: ColumnStyle;
+ readonly items: readonly ColumnItem[];
+};
+export type TopThreeProgram = {
+ readonly contract: "svml.top-three-program@1";
+ readonly id: string;
+ readonly frame: SpatialFrame;
+ readonly schedule: RankingSchedule;
+ readonly style: TopThreeStyle;
+ readonly items: readonly TopThreeItem[];
+};
+export type TypewriterListProgram = {
+ readonly contract: "svml.typewriter-list-program@1";
+ readonly id: string;
+ readonly title: string;
+ readonly frame: SpatialFrame;
+ readonly schedule: RankingSchedule;
+ readonly style: TypewriterListStyle;
+ readonly items: readonly TypewriterItem[];
+};
+
+export type RankingProgram = TierBoardProgram | ColumnProgram | TopThreeProgram | TypewriterListProgram;
+
+export type RankingSoundEvent = {
+ readonly id: string;
+ readonly itemId: string;
+ readonly kind: "appear" | "move";
+ readonly frame: number;
+};
+
+export type RankingSoundEventPlan = {
+ readonly contract: "svml.ranking-sound-event-plan@1";
+ readonly id: string;
+ readonly variant: RankingVariant;
+ readonly events: readonly RankingSoundEvent[];
+};
+
+export type RankingSoundSet = {
+ readonly contract: "svml.ranking-sound-set@1";
+ readonly appear?: SynchronizedMedia;
+ readonly move?: SynchronizedMedia;
+};
+
+export type RankingVisualProduct = {
+ readonly track: VisualTrack;
+};
+
+export type RankingAudioProduct = {
+ readonly track: AudioTrack;
+};
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
new file mode 100644
index 00000000..7495edd1
--- /dev/null
+++ b/packages/ranking/test/ranking.test.ts
@@ -0,0 +1,454 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { videoContractManifests } from "../../test-support/video-domain.js";
+
+import { createResolvedClosure } from "@narratage/core";
+import type { FontArtifactRef, SynchronizedMedia } from "@narratage/media";
+import { mediaTypes } from "@narratage/media";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import { sealProgramSpace } from "@narratage/program-space";
+import { digestOf } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import { sealSpatialFrame } from "@narratage/spatial";
+import type { SvsRecipe } from "@narratage/svs";
+
+import {
+ appendColumnItem,
+ appendRankingItemSpec,
+ appendRankingSound,
+ appendTierBoardItem,
+ appendTopThreeItem,
+ appendTypewriterItem,
+ buildColumnProgram,
+ buildColumnSoundEvents,
+ buildRankingSchedule,
+ buildTierBoardProgram,
+ buildTierBoardSoundEvents,
+ buildTopThreeProgram,
+ buildTopThreeSoundEvents,
+ buildTypewriterListProgram,
+ buildTypewriterSoundEvents,
+ createColumnItemSet,
+ createRankingItemSpecSet,
+ createRankingSoundSet,
+ createTierBoardItemSet,
+ createTopThreeItemSet,
+ createTypewriterItemSet,
+ decodeColumnStyle,
+ decodeColumnStyleSurface,
+ decodeColumnSurface,
+ decodeTierBoardStyle,
+ decodeTierBoardStyleSurface,
+ decodeTierBoardSurface,
+ decodeTopThreeStyle,
+ decodeTopThreeStyleSurface,
+ decodeTopThreeSurface,
+ decodeTypewriterListStyle,
+ decodeTypewriterListStyleSurface,
+ decodeTypewriterListSurface,
+ graphemes,
+ renderColumn,
+ renderRankingAudio,
+ renderTierBoard,
+ renderTopThree,
+ renderTypewriterList,
+ rankingManifest,
+ rankingTypes,
+ sealRankingHeader,
+} from "@narratage/ranking";
+import type {
+ ColumnItemSpec,
+ RankingHeader,
+ RankingItemSpec,
+ RankingSchedule,
+ TierBoardItemSpec,
+ TopThreeItemSpec,
+ TypewriterItemSpec,
+} from "@narratage/ranking";
+import { narrativeTypes } from "@narratage/narrative";
+import { programSpaceTypes } from "@narratage/program-space";
+import { semanticMapTypes } from "@narratage/semantic-map";
+import { spatialTypes } from "@narratage/spatial";
+import { svsRecipeType } from "@narratage/svs";
+import type {
+ StructuredElement,
+ StructuredNode,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+
+const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 8,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const frame = sealSpatialFrame({
+ contract: "svml.spatial-frame@1", xPx: 40, yPx: 80, widthPx: 720, heightPx: 560,
+});
+const map: CompleteSemanticMap = {
+ contract: "svml.complete-semantic-map@1",
+ tokens: [],
+ anchors: [
+ { identity: "outer-start", timeSec: 10 / 30, frame: 10 },
+ { identity: "one", timeSec: 1, frame: 30 },
+ { identity: "two", timeSec: 70 / 30, frame: 70 },
+ { identity: "three", timeSec: 110 / 30, frame: 110 },
+ { identity: "four", timeSec: 150 / 30, frame: 150 },
+ { identity: "terminal", timeSec: 190 / 30, frame: 190 },
+ { identity: "outer-end", timeSec: 230 / 30, frame: 230 },
+ ],
+};
+const outer: NarrativeSelectionRef = {
+ contract: "svml.narrative-selection@1", id: "ranking-window",
+ occurrences: [{ occurrence: 0, startAnchorId: "outer-start", endAnchorId: "outer-end" }],
+};
+const terminal: NarrativeMomentRef = {
+ contract: "svml.narrative-moment@1", id: "ranking-complete",
+ occurrences: [{ occurrence: 0, anchorId: "terminal" }],
+};
+const triggers = (count: number): NarrativeMomentRef => ({
+ contract: "svml.narrative-moment@1", id: "next-rank",
+ occurrences: ["one", "two", "three", "four"].slice(0, count)
+ .map((anchorId, occurrence) => ({ occurrence, anchorId })),
+});
+const font: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ sources: [{ artifact: { kind: "blob", digest: digestOf("ranking-font"), size: 32, mediaType: "font/woff2" } }],
+ weight: 700,
+ style: "normal",
+};
+const recipe = (path: string, properties: SvsRecipe["properties"] = {}): SvsRecipe => ({
+ contract: "svml.svs-recipe@1", path, properties,
+});
+const image = (id: string) => ({ kind: "blob" as const, digest: digestOf(`ranking-image:${id}`), size: 64, mediaType: "image/png" });
+const header = (variant: RankingHeader["variant"], id: string = variant) => sealRankingHeader({
+ contract: "svml.ranking-header@1", id, variant,
+});
+
+function specs(headerValue: RankingHeader, values: readonly RankingItemSpec[]) {
+ let set = createRankingItemSpecSet(headerValue);
+ for (const value of values) set = appendRankingItemSpec(set, value);
+ return set;
+}
+
+function schedule(headerValue: RankingHeader, values: readonly RankingItemSpec[]): RankingSchedule {
+ return buildRankingSchedule({
+ header: headerValue, items: specs(headerValue, values), map, space, outer,
+ triggers: triggers(values.length), terminal,
+ });
+}
+
+const tierSpec = (id: string, tier: string, entry: "direct" | "stage" = "direct"): TierBoardItemSpec => ({
+ contract: "svml.tier-board-item-spec@1", variant: "tier-board", id, tier, entry,
+});
+const columnSpec = (id: string): ColumnItemSpec => ({
+ contract: "svml.column-item-spec@1", variant: "column", id, label: id.toUpperCase(),
+});
+const topSpec = (id: string): TopThreeItemSpec => ({
+ contract: "svml.top-three-item-spec@1", variant: "top-three", id, label: id.toUpperCase(),
+});
+const typeSpec = (id: string, text: string, winner = false): TypewriterItemSpec => ({
+ contract: "svml.typewriter-item-spec@1", variant: "typewriter-list", id, text, winner,
+});
+
+test("RankingSchedule zips authored item and Moment order and preserves a settled suffix", () => {
+ const owner = header("column", "tools");
+ const value = schedule(owner, [columnSpec("fourth"), columnSpec("third"), columnSpec("second")]);
+ assert.deepEqual(value.entries.map((entry) => [entry.itemId, entry.triggerOccurrenceId, entry.stage, entry.cumulative]), [
+ ["fourth", "next-rank#0", { startFrame: 30, endFrameExclusive: 70 }, { startFrame: 30, endFrameExclusive: 230 }],
+ ["third", "next-rank#1", { startFrame: 70, endFrameExclusive: 110 }, { startFrame: 70, endFrameExclusive: 230 }],
+ ["second", "next-rank#2", { startFrame: 110, endFrameExclusive: 190 }, { startFrame: 110, endFrameExclusive: 230 }],
+ ]);
+ assert.deepEqual(value.entries.at(-1)?.settled, { startFrame: 190, endFrameExclusive: 230 });
+});
+
+test("RankingSchedule rejects cardinality, outer/terminal ambiguity and authored physical reversal", () => {
+ const owner = header("column");
+ const values = [columnSpec("a"), columnSpec("b")];
+ assert.throws(() => buildRankingSchedule({
+ header: owner, items: specs(owner, values), map, space, outer, triggers: triggers(1), terminal,
+ }), /cardinality/u);
+ assert.throws(() => buildRankingSchedule({
+ header: owner, items: specs(owner, values), map, space,
+ outer: { ...outer, occurrences: [...outer.occurrences, { ...outer.occurrences[0]!, occurrence: 1 }] },
+ triggers: triggers(2), terminal,
+ }), /exactly one/u);
+ assert.throws(() => buildRankingSchedule({
+ header: owner, items: specs(owner, values), map, space, outer,
+ triggers: { ...triggers(2), occurrences: [triggers(2).occurrences[1]!, triggers(2).occurrences[0]!] }, terminal,
+ }), /strictly increasing/u);
+});
+
+test("variant Style decoders reject unknown Recipes and keep exact fonts and independent stacks", () => {
+ const tier = decodeTierBoardStyle(recipe("ranking.tier", {
+ rows: "s:S:#ef4444|a:A:#22c55e", "board-stack": 8, "stage-stack": 20, "item-stack": 31,
+ }), font);
+ assert.deepEqual(tier.style.rows.map((row) => row.id), ["s", "a"]);
+ assert.equal(tier.style.text.fonts[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);
+ assert.deepEqual([tier.style.boardStackingOrder, tier.style.stageStackingOrder, tier.style.itemStackingOrder], [8, 20, 31]);
+ assert.throws(() => decodeColumnStyle(recipe("ranking.column", { "tier-only": 1 }), font), /does not accept/u);
+ assert.equal(decodeTopThreeStyle(recipe("ranking.top"), font).style.slotColors.length, 3);
+ assert.equal(decodeTypewriterListStyle(recipe("ranking.typewriter"), font).style.framesPerGrapheme, 2);
+});
+
+test("TierBoard owns cumulative direct/stage placement and rejects impossible stages", () => {
+ const owner = header("tier-board", "tiers");
+ const semantic = [tierSpec("alpha", "s", "stage"), tierSpec("beta", "a")];
+ const style = decodeTierBoardStyle(recipe("ranking.tier", {
+ rows: "s:S:#ef4444|a:A:#22c55e", "appear-frames": 5, "move-frames": 8,
+ }), font).style;
+ let set = createTierBoardItemSet();
+ set = appendTierBoardItem(set, semantic[0]!, image("alpha"));
+ set = appendTierBoardItem(set, semantic[1]!, image("beta"));
+ const program = buildTierBoardProgram(owner, frame, schedule(owner, semantic), style, set);
+ const track = renderTierBoard(space, program);
+ assert.deepEqual(track.presents.map((item) => item.stacking.order).sort((a, b) => a - b), [20, 25, 30, 30, 30, 30]);
+ assert.equal(track.presents.find((item) => item.id.endsWith(":item:alpha:settled"))?.span.endFrameExclusive, 230);
+ const tightTerminal = { ...terminal, occurrences: [{ occurrence: 0, anchorId: "two" }] };
+ assert.throws(() => buildRankingSchedule({
+ header: owner, items: specs(owner, semantic), map, space, outer, triggers: triggers(2), terminal: tightTerminal,
+ }), /outside|strictly increasing/u);
+});
+
+test("Column has one active stage, cumulative settled rows and truly optional icons", () => {
+ const owner = header("column", "column");
+ const semantic = [columnSpec("one"), columnSpec("two"), columnSpec("three")];
+ const style = decodeColumnStyle(recipe("ranking.column", { "appear-frames": 4, "move-frames": 6 }), font).style;
+ let set = createColumnItemSet();
+ set = appendColumnItem(set, semantic[0]!);
+ set = appendColumnItem(set, semantic[1]!, image("two"));
+ set = appendColumnItem(set, semantic[2]!);
+ const value = schedule(owner, semantic);
+ const program = buildColumnProgram(owner, frame, value, style, set);
+ const track = renderColumn(space, program);
+ const items = track.presents.filter((item) => item.id.includes(":item:") && item.id.endsWith(":stage"));
+ assert.deepEqual(items.map((item) => item.span.startFrame), [30, 70, 110]);
+ assert.equal(items[0]?.elements.some((item) => item.kind === "image"), false);
+ assert.equal(items[1]?.elements.some((item) => item.kind === "image"), true);
+ assert.equal(value.entries.filter((entry) => entry.stage.startFrame <= 80 && 80 < entry.stage.endFrameExclusive).length, 1);
+});
+
+test("TopThree accepts one to three optional-image Items and removes active accent in the settled suffix", () => {
+ const owner = header("top-three", "podium");
+ const semantic = [topSpec("gold"), topSpec("silver"), topSpec("bronze")];
+ const style = decodeTopThreeStyle(recipe("ranking.top", { "appear-frames": 4 }), font).style;
+ let set = createTopThreeItemSet();
+ set = appendTopThreeItem(set, semantic[0]!, image("gold"));
+ set = appendTopThreeItem(set, semantic[1]!);
+ set = appendTopThreeItem(set, semantic[2]!, image("bronze"));
+ const value = schedule(owner, semantic);
+ const program = buildTopThreeProgram(owner, frame, value, style, set);
+ const track = renderTopThree(space, program);
+ const active = track.presents.find((item) => item.id.endsWith(":item:bronze:stage"))!;
+ const settled = track.presents.find((item) => item.id.endsWith(":item:bronze:settled"))!;
+ const accent = active.elements.find((item) => item.id === "accent");
+ assert.equal(accent?.animation?.keyframes.at(-1)?.atFrame, value.entries[2]!.stage.endFrameExclusive - value.entries[2]!.triggerFrame);
+ assert.equal(settled.elements.some((item) => item.id === "accent"), false);
+ const fourth = topSpec("fourth");
+ let tooMany = appendTopThreeItem(set, fourth);
+ assert.throws(() => buildTopThreeProgram(owner, frame,
+ schedule(owner, [...semantic, fourth]), style, tooMany), /at most three/u);
+});
+
+test("Typewriter uses Unicode graphemes, explicit emphasis and winner timing without generic Text masquerading", () => {
+ const owner = header("typewriter-list", "list");
+ const first: TypewriterItemSpec = {
+ ...typeSpec("first", "A👩‍💻B", true), emphasis: { start: 1, endExclusive: 2 },
+ };
+ const semantic = [first, typeSpec("second", "Done")];
+ const style = decodeTypewriterListStyle(recipe("ranking.typewriter", {
+ "frames-per-grapheme": 2, "winner-frames": 4,
+ }), font).style;
+ assert.deepEqual(graphemes(first.text), ["A", "👩‍💻", "B"]);
+ let set = createTypewriterItemSet();
+ set = appendTypewriterItem(set, first);
+ set = appendTypewriterItem(set, semantic[1]!);
+ const program = buildTypewriterListProgram(owner, "Tools", frame, schedule(owner, semantic), style, set);
+ const track = renderTypewriterList(space, program);
+ const row = track.presents.find((item) => item.id.endsWith(":item:first:stage"))!;
+ const text = row.elements.find((item) => item.kind === "text-flow");
+ assert.equal(text?.kind, "text-flow");
+ assert.equal(text?.sequences[0]?.range.endExclusive, 3);
+ const emphasis = text?.document.paragraphs[0]?.inlines[1];
+ assert.equal(emphasis?.kind, "text");
+ assert.equal(emphasis.kind === "text" ? emphasis.text : undefined, "👩‍💻");
+ assert.ok(row.elements.some((item) => item.kind === "text" && item.text === "★"));
+ assert.throws(() => buildTypewriterListProgram(owner, "Tools", frame, schedule(owner, semantic), {
+ ...style, framesPerGrapheme: 20,
+ }, set), /requires/u);
+});
+
+const sound = (id: string, sampleFrames = 4_800): SynchronizedMedia => ({
+ contract: "svml.synchronized-media@1",
+ timeline: { spanAuthority: "audio", frameRate: { numerator: 30, denominator: 1 }, frameCount: 3,
+ sampleRate: 48_000, sampleFrames },
+ sourceMap: {
+ sourceOriginPts: { ticks: "0", timeBase: { numerator: 1, denominator: 48_000 } },
+ sourceEndPts: { ticks: String(sampleFrames), timeBase: { numerator: 1, denominator: 48_000 } },
+ audioTrimStartSamples: 0, audioTrimEndSamples: 0, audioHeadSamples: 0,
+ audioContentSamples: sampleFrames, audioTailSamples: 0,
+ },
+ audio: {
+ artifact: { kind: "blob", digest: digestOf(`ranking-sound:${id}`), size: 128, mediaType: "audio/wav" },
+ sourceStreamIndex: 0, codec: "pcm_s16le", sampleRate: 48_000, channels: 2, sampleFrames, loudness: "preserved",
+ },
+});
+
+test("visual and sound event plans share exact phase frames while absent sound stays an independent branch", () => {
+ const owner = header("column", "sound-column");
+ const semantic = [columnSpec("one"), columnSpec("two")];
+ const decoded = decodeColumnStyle(recipe("ranking.column", {
+ "appear-frames": 4, "move-frames": 6, "appear-gain": 0.8, "move-gain": 0.6,
+ }), font);
+ const value = schedule(owner, semantic);
+ const events = buildColumnSoundEvents(value, decoded.style, specs(owner, semantic));
+ assert.deepEqual(events.events.map((item) => [item.kind, item.frame]), [
+ ["appear", 30], ["move", 64], ["appear", 70], ["move", 184],
+ ]);
+ let sounds = createRankingSoundSet();
+ sounds = appendRankingSound(sounds, "appear", sound("appear"));
+ sounds = appendRankingSound(sounds, "move", sound("move"));
+ const audio = renderRankingAudio(space, events, decoded.sound, sounds);
+ assert.deepEqual(audio.clips.map((clip) => clip.target.startSample), [48_000, 102_400, 112_000, 294_400]);
+ assert.deepEqual(audio.clips.map((clip) => clip.gain), [0.8, 0.6, 0.8, 0.6]);
+});
+
+test("each component owns a distinct event law and repeated lowering is canonical", () => {
+ const tierOwner = header("tier-board", "tier-events");
+ const tierItems = [tierSpec("direct", "s"), tierSpec("stage", "a", "stage")];
+ const tier = decodeTierBoardStyle(recipe("ranking.tier", { rows: "s:S:#ef4444|a:A:#22c55e" }), font).style;
+ assert.deepEqual(buildTierBoardSoundEvents(schedule(tierOwner, tierItems), tier, specs(tierOwner, tierItems)).events.map((item) => item.kind),
+ ["appear", "appear", "move"]);
+
+ const topOwner = header("top-three", "top-events");
+ const topItems = [topSpec("one")];
+ const top = decodeTopThreeStyle(recipe("ranking.top"), font).style;
+ assert.deepEqual(buildTopThreeSoundEvents(schedule(topOwner, topItems), top, specs(topOwner, topItems)).events.map((item) => item.kind), ["appear"]);
+
+ const typeOwner = header("typewriter-list", "type-events");
+ const typeItems = [typeSpec("winner", "ABC", true)];
+ const type = decodeTypewriterListStyle(recipe("ranking.typewriter"), font).style;
+ assert.deepEqual(buildTypewriterSoundEvents(schedule(typeOwner, typeItems), type, specs(typeOwner, typeItems)).events.map((item) => item.kind),
+ ["appear", "move"]);
+
+ const columnOwner = header("column", "deterministic");
+ const columnItems = [columnSpec("one")];
+ const columnStyle = decodeColumnStyle(recipe("ranking.column"), font).style;
+ let set = appendColumnItem(createColumnItemSet(), columnItems[0]!);
+ const program = buildColumnProgram(columnOwner, frame, schedule(columnOwner, columnItems), columnStyle, set);
+ assert.deepEqual(renderColumn(space, program), renderColumn(space, program));
+});
+
+test("all four author Surfaces preserve explicit semantic, spatial, font, image and optional sound graph edges", async () => {
+ createResolvedClosure([...videoContractManifests, rankingManifest]);
+ const range = { source: "ranking.svml", start: 0, end: 1 };
+ const ref = (path: string): TextAttributeValue => ({ kind: "reference", path });
+ const node = (name: string, attributes: Record<string, TextAttributeValue>, children: StructuredNode[] = []): StructuredElement => ({ kind: "element", name, attributes, children, range });
+ const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({ path, ref: { kind: "record", id: path }, type });
+ const inlineReference = (path: string, type: SurfaceResolvedReference["type"], value: unknown): SurfaceResolvedReference => ({
+ path, ref: { kind: "record", id: path }, type,
+ record: { value: { kind: "inline", value } } as never,
+ });
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["map", plain("map", semanticMapTypes.complete)],
+ ["space", plain("space", programSpaceTypes.programSpace)],
+ ["frame", plain("frame", spatialTypes.frame)],
+ ["outer", plain("outer", narrativeTypes.selection)],
+ ["triggers", plain("triggers", narrativeTypes.moment)],
+ ["terminal", plain("terminal", narrativeTypes.moment)],
+ ["icon-1", plain("icon-1", mediaTypes.blobArtifact)],
+ ["icon-2", plain("icon-2", mediaTypes.blobArtifact)],
+ ["appear", plain("appear", mediaTypes.synchronized)],
+ ["move", plain("move", mediaTypes.synchronized)],
+ ["font", inlineReference("font", mediaTypes.fontArtifact, font)],
+ ]);
+ const styleCases = [
+ ["tier-style", rankingTypes.tierStyle, decodeTierBoardStyleSurface, { rows: "s:S:#ef4444|a:A:#22c55e" }],
+ ["column-style", rankingTypes.columnStyle, decodeColumnStyleSurface, {}],
+ ["top-style", rankingTypes.topThreeStyle, decodeTopThreeStyleSurface, {}],
+ ["type-style", rankingTypes.typewriterStyle, decodeTypewriterListStyleSurface, {}],
+ ] as const;
+ for (const [id, type, handler, properties] of styleCases) {
+ references.set(`${id}-recipe`, inlineReference(`${id}-recipe`, svsRecipeType, recipe(id, properties)));
+ const result = await handler({
+ sourceName: "ranking.svml",
+ element: node(`ranking:${type.name.replace(/Style$/u, "Style")}`, { id, recipe: ref(`${id}-recipe`), font: ref("font") }),
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ assert.deepEqual(result.records.map((record) => record.id), [id, `${id}.sound`]);
+ const visualRecord = result.records[0]!;
+ const soundRecord = result.records[1]!;
+ references.set(id, { path: id, ref: { kind: "record", id }, type, record: visualRecord as never });
+ references.set(`${id}.sound`, { path: `${id}.sound`, ref: { kind: "record", id: `${id}.sound` }, type: rankingTypes.soundStyle, record: soundRecord as never });
+ }
+ const cases = [
+ [decodeTierBoardSurface, node("ranking:TierBoard", {
+ id: "tier", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
+ triggers: ref("triggers"), terminal: ref("terminal"), style: ref("tier-style"),
+ }, [node("ranking:TierItem", { id: "tier-one", tier: "s", entry: "stage", icon: ref("icon-1") })])],
+ [decodeColumnSurface, node("ranking:Column", {
+ id: "column", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
+ triggers: ref("triggers"), terminal: ref("terminal"), style: ref("column-style"),
+ "appear-sound": ref("appear"), "move-sound": ref("move"),
+ }, [node("ranking:ColumnItem", { id: "column-one", label: "One" }), node("ranking:ColumnItem", { id: "column-two", label: "Two", icon: ref("icon-2") })])],
+ [decodeTopThreeSurface, node("ranking:TopThree", {
+ id: "top", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
+ triggers: ref("triggers"), terminal: ref("terminal"), style: ref("top-style"),
+ }, [node("ranking:TopThreeItem", { label: "First" }), node("ranking:TopThreeItem", { label: "Second", icon: ref("icon-1") })])],
+ [decodeTypewriterListSurface, node("ranking:TypewriterList", {
+ id: "typed", title: "Proof", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
+ triggers: ref("triggers"), terminal: ref("terminal"), style: ref("type-style"),
+ }, [node("ranking:TypewriterItem", { winner: "true", "emphasis-start": "1", "emphasis-end": "2" }, [{ kind: "text", value: "A👩‍💻B", range }])])],
+ ] as const;
+ for (const [handler, element] of cases) {
+ const result = await handler({
+ sourceName: "ranking.svml", element,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ assert.equal(result.components.length, 1);
+ assert.equal(result.fragments.length, 1);
+ const fragment = result.fragments[0]!;
+ assert.ok(fragment.exports.some((output) => output.name === "schedule"));
+ assert.ok(fragment.exports.some((output) => output.name === "program"));
+ assert.ok(fragment.exports.some((output) => output.name === "visual"));
+ assert.ok(fragment.exports.find((output) => output.name === "visual")?.semanticInputs.includes("frame"));
+ }
+ const column = await decodeColumnSurface({
+ sourceName: "ranking.svml", element: cases[1][1],
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ const audio = column.fragments[0]!.exports.find((output) => output.name === "audio");
+ assert(audio !== undefined);
+ assert.equal(audio.semanticInputs.includes("frame"), false);
+ assert.equal(audio.semanticInputs.some((name) => name.endsWith("icon")), false);
+ assert.deepEqual(Object.keys(column.components[0]!.outputs).sort(), ["audio", "program", "schedule", "visual"]);
+});
+
+test("Ranking author Surfaces fail closed on impossible image and sound combinations", async () => {
+ const range = { source: "ranking.svml", start: 0, end: 1 };
+ const ref = (path: string): TextAttributeValue => ({ kind: "reference", path });
+ const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({ path, ref: { kind: "record", id: path }, type });
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["map", plain("map", semanticMapTypes.complete)], ["space", plain("space", programSpaceTypes.programSpace)],
+ ["frame", plain("frame", spatialTypes.frame)], ["outer", plain("outer", narrativeTypes.selection)],
+ ["triggers", plain("triggers", narrativeTypes.moment)], ["terminal", plain("terminal", narrativeTypes.moment)],
+ ["style", plain("style", rankingTypes.tierStyle)], ["style.sound", plain("style.sound", rankingTypes.soundStyle)],
+ ["move", plain("move", mediaTypes.synchronized)],
+ ]);
+ const common = { id: "bad", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"), triggers: ref("triggers"), terminal: ref("terminal"), style: ref("style") };
+ const context = (element: StructuredElement) => ({
+ sourceName: "ranking.svml", element, resolveReference: (path: string) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ assert.throws(() => decodeTierBoardSurface(context({
+ kind: "element", name: "ranking:TierBoard", attributes: common,
+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s" }, children: [], range }], range,
+ })), /icon/u);
+ assert.throws(() => decodeTierBoardSurface(context({
+ kind: "element", name: "ranking:TierBoard", attributes: { ...common, "move-sound": ref("move") },
+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", icon: ref("missing") }, children: [], range }], range,
+ })), /wrong Type|move-sound/u);
+});
diff --git a/packages/spatial/README.md b/packages/spatial/README.md
index 4c9c61c1..aef6b0bf 100644
--- a/packages/spatial/README.md
+++ b/packages/spatial/README.md
@@ -4,6 +4,6 @@ Shared video-domain geometry: explicit Canvas coordinates, Points, Frames, Paths
and deterministic two-frame content fitting. It owns no timing, Paint, motion, media decoding,
renderer, Provider or Core behavior.
-The package exposes self-described `Canvas`, `Frame`, `AnchoredFrame` and `AspectFrame` author
-Surfaces plus pure geometry functions and fixed-port Producers. See
+The package exposes self-described `Canvas`, `Point`, `Path`, `Extent`, `Frame`, `AnchoredFrame` and
+`AspectFrame` author Surfaces plus pure geometry functions and fixed-port Producers. See
[`../../spec/spatial-layout.md`](../../spec/spatial-layout.md).
diff --git a/packages/spatial/src/activation.ts b/packages/spatial/src/activation.ts
index 83d5a691..f4e6d3ec 100644
--- a/packages/spatial/src/activation.ts
+++ b/packages/spatial/src/activation.ts
@@ -6,6 +6,8 @@ import {
decodeCanvasSurface,
decodeExtentSurface,
decodeFrameSurface,
+ decodePathSurface,
+ decodePointSurface,
} from "./surface.js";
import {
spatialManifest,
@@ -21,6 +23,8 @@ export const svmlPackage = {
components: [spatialComponent],
hostFacets: [
createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "canvas", mode: "structured", implementationDigest: spatialSurfaceDigests.canvas, handler: decodeCanvasSurface }),
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "point", mode: "structured", implementationDigest: spatialSurfaceDigests.point, handler: decodePointSurface }),
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "path", mode: "structured", implementationDigest: spatialSurfaceDigests.path, handler: decodePathSurface }),
createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "extent", mode: "structured", implementationDigest: spatialSurfaceDigests.extent, handler: decodeExtentSurface }),
createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "frame", mode: "structured", implementationDigest: spatialSurfaceDigests.frame, handler: decodeFrameSurface }),
createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "anchored-frame", mode: "structured", implementationDigest: spatialSurfaceDigests.anchoredFrame, handler: decodeAnchoredFrameSurface }),
diff --git a/packages/spatial/src/index.ts b/packages/spatial/src/index.ts
index 7b33f503..6d982619 100644
--- a/packages/spatial/src/index.ts
+++ b/packages/spatial/src/index.ts
@@ -16,12 +16,20 @@ export {
spatialSurfaceDigests,
spatialTypes,
} from "./manifest.js";
-export { contentFitSchema, intrinsicExtentSchema, spatialFrameSchema } from "./schema.js";
+export {
+ contentFitSchema,
+ intrinsicExtentSchema,
+ spatialFrameSchema,
+ spatialPathSchema,
+ spatialPointSchema,
+} from "./schema.js";
export {
decodeAnchoredFrameSurface,
decodeAspectFrameSurface,
decodeCanvasSurface,
decodeExtentSurface,
decodeFrameSurface,
+ decodePathSurface,
+ decodePointSurface,
} from "./surface.js";
export type * from "./types.js";
diff --git a/packages/spatial/src/manifest.ts b/packages/spatial/src/manifest.ts
index eab3615f..5f5fd2c8 100644
--- a/packages/spatial/src/manifest.ts
+++ b/packages/spatial/src/manifest.ts
@@ -18,6 +18,8 @@ import {
export const spatialModuleRef = { name: "@narratage/spatial", version: "0.0.0-dev" } as const;
export const spatialSurfaceDigests = {
canvas: digestOf("@narratage/spatial/canvas-surface@1"),
+ point: digestOf("@narratage/spatial/point-surface@1"),
+ path: digestOf("@narratage/spatial/path-surface@1"),
extent: digestOf("@narratage/spatial/extent-surface@1"),
frame: digestOf("@narratage/spatial/frame-surface@1"),
anchoredFrame: digestOf("@narratage/spatial/anchored-frame-surface@1"),
@@ -68,6 +70,8 @@ export const spatialManifest: ModuleManifest = {
capabilities: [],
surfaces: [
{ name: "canvas", tag: "Canvas", mode: "structured", outputs: [spatialTypes.canvas], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/canvas-surface", digest: spatialSurfaceDigests.canvas } },
+ { name: "point", tag: "Point", mode: "structured", outputs: [spatialTypes.point], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/point-surface", digest: spatialSurfaceDigests.point } },
+ { name: "path", tag: "Path", mode: "structured", outputs: [spatialTypes.path], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/path-surface", digest: spatialSurfaceDigests.path } },
{ name: "extent", tag: "Extent", mode: "structured", outputs: [spatialTypes.extent], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/extent-surface", digest: spatialSurfaceDigests.extent } },
{ name: "frame", tag: "Frame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.frameEdgesProgram], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/frame-surface", digest: spatialSurfaceDigests.frame } },
{ name: "anchored-frame", tag: "AnchoredFrame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.anchoredFrameProgram], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/anchored-frame-surface", digest: spatialSurfaceDigests.anchoredFrame } },
diff --git a/packages/spatial/src/surface.ts b/packages/spatial/src/surface.ts
index 0888c161..4849cdc4 100644
--- a/packages/spatial/src/surface.ts
+++ b/packages/spatial/src/surface.ts
@@ -15,13 +15,15 @@ import {
frameEdgesFragment,
} from "./fragment.js";
import { spatialTypes } from "./manifest.js";
-import { sealCanvasSpace, sealIntrinsicExtent } from "./geometry.js";
+import { assertSpatialPath, sealCanvasSpace, sealIntrinsicExtent, sealSpatialPoint } from "./geometry.js";
import type {
AnchoredFrameProgram,
AspectFrameProgram,
FrameEdgesProgram,
SpatialAnchor,
SpatialLength,
+ SpatialPath,
+ SpatialPathCommand,
} from "./types.js";
function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
@@ -122,6 +124,81 @@ export const decodeCanvasSurface: StructuredSurfaceHandler = ({ element }) => {
return { records: [{ id, type: spatialTypes.canvas, value: { kind: "inline", value: canvas as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
};
+export const decodePointSurface: StructuredSurfaceHandler = ({ element }) => {
+ exact(element, ["id", "x", "y"], ["id", "x", "y"]);
+ const id = text(element, "id");
+ const point = sealSpatialPoint({
+ contract: "svml.spatial-point@1",
+ xPx: number(element, "x"),
+ yPx: number(element, "y"),
+ });
+ return {
+ records: [{ id, type: spatialTypes.point, value: { kind: "inline", value: point as unknown as CanonicalValue }, range: element.range }],
+ components: [], fragments: [],
+ };
+};
+
+function commandNumber(element: StructuredElement, name: string): number {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be finite.`);
+ const parsed = Number(value);
+ if (!Number.isFinite(parsed)) throw new Error(`${element.name}.${name} must be finite.`);
+ return parsed;
+}
+
+function pathCommand(element: StructuredElement): SpatialPathCommand {
+ const name = element.name.slice(element.name.lastIndexOf(":") + 1);
+ if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
+ throw new Error(`${element.name} must be empty.`);
+ }
+ if (name === "Move" || name === "Line") {
+ exact(element, ["x", "y"], ["x", "y"]);
+ return { kind: name === "Move" ? "move" : "line", xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y") };
+ }
+ if (name === "Quadratic") {
+ exact(element, ["control-x", "control-y", "x", "y"], ["control-x", "control-y", "x", "y"]);
+ return {
+ kind: "quadratic",
+ controlX: commandNumber(element, "control-x"), controlY: commandNumber(element, "control-y"),
+ xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y"),
+ };
+ }
+ if (name === "Cubic") {
+ exact(element, ["control1-x", "control1-y", "control2-x", "control2-y", "x", "y"], ["control1-x", "control1-y", "control2-x", "control2-y", "x", "y"]);
+ return {
+ kind: "cubic",
+ control1X: commandNumber(element, "control1-x"), control1Y: commandNumber(element, "control1-y"),
+ control2X: commandNumber(element, "control2-x"), control2Y: commandNumber(element, "control2-y"),
+ xPx: commandNumber(element, "x"), yPx: commandNumber(element, "y"),
+ };
+ }
+ if (name === "Close") {
+ exact(element, [], []);
+ return { kind: "close" };
+ }
+ throw new Error(`${element.name} is not a Spatial Path command.`);
+}
+
+export const decodePathSurface: StructuredSurfaceHandler = ({ element }) => {
+ const unknown = Object.keys(element.attributes).filter((name) => name !== "id");
+ if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+ const id = text(element, "id");
+ const commands: SpatialPathCommand[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Path commands.`);
+ continue;
+ }
+ commands.push(pathCommand(child));
+ }
+ const path: SpatialPath = { contract: "svml.spatial-path@1", commands };
+ assertSpatialPath(path);
+ return {
+ records: [{ id, type: spatialTypes.path, value: { kind: "inline", value: path as unknown as CanonicalValue }, range: element.range }],
+ components: [], fragments: [],
+ };
+};
+
export const decodeExtentSurface: StructuredSurfaceHandler = ({ element }) => {
exact(element, ["id", "width", "height"], ["id", "width", "height"]);
const id = text(element, "id");
diff --git a/packages/spatial/test/spatial.test.ts b/packages/spatial/test/spatial.test.ts
index ba81941a..d710114a 100644
--- a/packages/spatial/test/spatial.test.ts
+++ b/packages/spatial/test/spatial.test.ts
@@ -18,6 +18,8 @@ import {
decodeAspectFrameSurface,
decodeCanvasSurface,
decodeFrameSurface,
+ decodePathSurface,
+ decodePointSurface,
fitContent,
frameFromEdges,
sealSpatialPath,
@@ -94,6 +96,70 @@ test("every ContentFit sizing mode resolves the independent Content Frame", () =
assert.deepEqual(fitContent(frame, portrait, centered("stretch")).contentFrame, frame);
});
+test("the complete aspect, sizing and equal-point matrix preserves the two-frame equations", () => {
+ const frames = [
+ { contract: "svml.spatial-frame@1" as const, xPx: -120, yPx: 40, widthPx: 600, heightPx: 1_000 },
+ { contract: "svml.spatial-frame@1" as const, xPx: 15, yPx: -80, widthPx: 1_000, heightPx: 600 },
+ { contract: "svml.spatial-frame@1" as const, xPx: 200, yPx: 300, widthPx: 800, heightPx: 800 },
+ ];
+ const extents = [
+ { contract: "svml.intrinsic-extent@1" as const, widthPx: 600, heightPx: 1_000 },
+ { contract: "svml.intrinsic-extent@1" as const, widthPx: 1_000, heightPx: 600 },
+ { contract: "svml.intrinsic-extent@1" as const, widthPx: 800, heightPx: 800 },
+ ];
+ const sizings = ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] as const;
+ const close = (actual: number, expected: number, label: string): void => {
+ assert.ok(Math.abs(actual - expected) < 1e-9, `${label}: ${actual} != ${expected}`);
+ };
+
+ for (const frame of frames) {
+ for (const extent of extents) {
+ for (const sizing of sizings) {
+ const content = fitContent(frame, extent, centered(sizing)).contentFrame;
+ close(content.xPx + content.widthPx / 2, frame.xPx + frame.widthPx / 2, `${sizing} center x`);
+ close(content.yPx + content.heightPx / 2, frame.yPx + frame.heightPx / 2, `${sizing} center y`);
+ if (sizing !== "stretch") {
+ close(content.widthPx / content.heightPx, extent.widthPx / extent.heightPx, `${sizing} aspect`);
+ }
+ if (sizing === "contain") {
+ assert.ok(content.widthPx <= frame.widthPx + 1e-9 && content.heightPx <= frame.heightPx + 1e-9);
+ assert.ok(Math.abs(content.widthPx - frame.widthPx) < 1e-9 || Math.abs(content.heightPx - frame.heightPx) < 1e-9);
+ } else if (sizing === "cover") {
+ assert.ok(content.widthPx + 1e-9 >= frame.widthPx && content.heightPx + 1e-9 >= frame.heightPx);
+ assert.ok(Math.abs(content.widthPx - frame.widthPx) < 1e-9 || Math.abs(content.heightPx - frame.heightPx) < 1e-9);
+ } else if (sizing === "fit-width") {
+ close(content.widthPx, frame.widthPx, "fit-width width");
+ } else if (sizing === "fit-height") {
+ close(content.heightPx, frame.heightPx, "fit-height height");
+ } else if (sizing === "native") {
+ close(content.widthPx, extent.widthPx, "native width");
+ close(content.heightPx, extent.heightPx, "native height");
+ } else if (sizing === "scale-down") {
+ assert.ok(content.widthPx <= extent.widthPx + 1e-9 && content.heightPx <= extent.heightPx + 1e-9);
+ assert.ok(content.widthPx <= frame.widthPx + 1e-9 && content.heightPx <= frame.heightPx + 1e-9);
+ } else {
+ close(content.widthPx, frame.widthPx, "stretch width");
+ close(content.heightPx, frame.heightPx, "stretch height");
+ }
+ }
+ }
+ }
+
+ const frame = { contract: "svml.spatial-frame@1" as const, xPx: -70, yPx: 110, widthPx: 400, heightPx: 400 };
+ const extent = { contract: "svml.intrinsic-extent@1" as const, widthPx: 200, heightPx: 200 };
+ const points = [0, 0.5, 1] as const;
+ for (const x of points) {
+ for (const y of points) {
+ const content = fitContent(frame, extent, {
+ contract: "svml.content-fit@1", sizing: "native",
+ framePoint: { x, y }, contentPoint: { x, y }, offsetPx: { x: 0, y: 0 }, constraint: "bounded",
+ }).contentFrame;
+ close(content.xPx + content.widthPx * x, frame.xPx + frame.widthPx * x, `equal point ${x},${y} x`);
+ close(content.yPx + content.heightPx * y, frame.yPx + frame.heightPx * y, `equal point ${x},${y} y`);
+ }
+ }
+});
+
test("unequal focal points and bounded/free policies remain explicit", () => {
const frame: SpatialFrame = { contract: "svml.spatial-frame@1", xPx: 10, yPx: 20, widthPx: 400, heightPx: 300 };
const fit: ContentFit = {
@@ -137,6 +203,8 @@ test("self-described Spatial Surfaces produce an explicit Canvas edge and finite
const closure = createResolvedClosure([spatialManifest]);
const surfaces = new TextSurfaceRegistry();
surfaces.registerStructured(spatialModuleRef, "canvas", spatialSurfaceDigests.canvas, decodeCanvasSurface);
+ surfaces.registerStructured(spatialModuleRef, "point", spatialSurfaceDigests.point, decodePointSurface);
+ surfaces.registerStructured(spatialModuleRef, "path", spatialSurfaceDigests.path, decodePathSurface);
surfaces.registerStructured(spatialModuleRef, "frame", spatialSurfaceDigests.frame, decodeFrameSurface);
surfaces.registerStructured(spatialModuleRef, "anchored-frame", spatialSurfaceDigests.anchoredFrame, decodeAnchoredFrameSurface);
surfaces.registerStructured(spatialModuleRef, "aspect-frame", spatialSurfaceDigests.aspectFrame, decodeAspectFrameSurface);
@@ -148,6 +216,11 @@ test("self-described Spatial Surfaces produce an explicit Canvas edge and finite
entry: source(`<svml>
<import as="space" from="@narratage/spatial@1"/>
<space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Point id="headline-origin" x="120" y="280"/>
+ <space:Path id="headline-path">
+ <space:Move x="120" y="280"/>
+ <space:Cubic control1-x="360" control1-y="180" control2-x="720" control2-y="380" x="960" y="280"/>
+ </space:Path>
<space:Frame id="safe" within={vertical} left="6%" top="4%" right="94%" bottom="96%"/>
<space:AnchoredFrame id="card" within={safe} x="50%" y="78%" width="82%" height="28%" anchor="center"/>
<space:AspectFrame id="sticker" within={safe} x="100%" y="100%" width="32%" aspect="9/16" anchor="bottom-right"/>
@@ -158,6 +231,8 @@ test("self-described Spatial Surfaces produce an explicit Canvas edge and finite
resolveSource() { throw new Error("Spatial fixture has no source imports."); },
});
assert.equal(resolveCompiledSourceExport(compiled, "vertical", spatialTypes.canvas).ref.kind, "record");
+ assert.equal(resolveCompiledSourceExport(compiled, "headline-origin", spatialTypes.point).ref.kind, "record");
+ assert.equal(resolveCompiledSourceExport(compiled, "headline-path", spatialTypes.path).ref.kind, "record");
const sticker = resolveCompiledSourceExport(compiled, "sticker", spatialTypes.frame);
assert.equal(sticker.ref.kind, "logical-output");
const build = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
@@ -165,9 +240,9 @@ test("self-described Spatial Surfaces produce an explicit Canvas edge and finite
targets: [{ output: sticker.ref.kind === "logical-output" ? sticker.ref.id : "", accepts: "exact" }],
satisfactions: [],
}));
- assert.deepEqual(build.plan.steps.map((step) => step.producer.name), [
+ assert.deepEqual(build.plan.steps.map((step) => step.producer.name).sort(), [
spatialProducers.canvasFrame.name,
spatialProducers.frameEdges.name,
spatialProducers.aspectFrame.name,
- ]);
+ ].sort());
});
diff --git a/packages/text-track/README.md b/packages/text-track/README.md
index b50a6654..3d0c3e21 100644
--- a/packages/text-track/README.md
+++ b/packages/text-track/README.md
@@ -3,9 +3,10 @@
Official provider-free Text overlay package. It owns a typed `TextTrackProgram` and lowers every
item into an independently timed and stacked Present in the public VisualTrack contract.
-The current `TextTrackProgram@1` is an executable vertical-slice fixture, not the frozen official
-Text authoring protocol. It proves package-to-IR lowering but does not yet reproduce the old
-three-box layout, exact-font and layered-decoration capability gate.
+The current `TextTrackProgram@1` implements the complete pre-release Point/Area/Path author model:
+bounded rich documents, exact font stacks, ordered Paint, frame/content/paragraph/line/run/word/
+grapheme boxes, deterministic overflow and Unicode-aware local motion. It is not yet a frozen
+public ABI because the shared Track and Visual IR freeze gates remain open.
An item spanning the complete ProgramSpace is a persistent overlay; a shorter item is timed. They
are not different Track kinds. Timing is projected through `@narratage/temporal`, and placement is
@@ -13,7 +14,8 @@ an explicit `SpatialFrame` input from `@narratage/spatial`; neither is hidden in
Recipe. The package exposes semantic typography rather than a rendering callback, arbitrary CSS or
cross-Track access.
-The provider-free `<text:Track>` Surface validates `.svs` Recipes, accepts explicit full or
-Selection timing plus a `SpatialFrame` edge for every Item, and produces the same TextTrackProgram
-without changing Core, Film, Composition or HyperFrames. Exact FontArtifact lowering and the full
-Point/Area/Path Text model remain pre-freeze work.
+The provider-free `<text:Track>` Surface validates `.svs` Recipes, accepts Program, Selection,
+Moment or explicit point-expression timing plus explicit Point/Frame/Path edges, and produces the
+same TextTrackProgram without changing Core or Film. `<text:Mask>` is a separate component that
+consumes one authored Text Program and one owned still Surface; advanced/multiline/Path masks fail
+closed and materialize through an independent package.
diff --git a/packages/text-track/package.json b/packages/text-track/package.json
index 5c055d64..12c065b5 100644
--- a/packages/text-track/package.json
+++ b/packages/text-track/package.json
@@ -13,6 +13,7 @@
"@narratage/component-kit": "workspace:*",
"@narratage/composition": "workspace:*",
"@narratage/elaborator": "workspace:*",
+ "@narratage/media": "workspace:*",
"@narratage/narrative": "workspace:*",
"@narratage/program-space": "workspace:*",
"@narratage/protocol": "workspace:*",
diff --git a/packages/text-track/src/activation.ts b/packages/text-track/src/activation.ts
index 43a462f1..9c867d78 100644
--- a/packages/text-track/src/activation.ts
+++ b/packages/text-track/src/activation.ts
@@ -1,7 +1,13 @@
import { createTextSurfaceHostFacet } from "@narratage/text";
import {
- decodeTextTrackSurface, textTrackComponent, textTrackManifest, textTrackModuleRef,
- textTrackSurfaceImplementationDigest,
+ decodeTextMotionSurface,
+ decodeTextMaskSurface,
+ decodeTextStyleSurface,
+ decodeTextTrackSurface,
+ textTrackComponent,
+ textTrackManifest,
+ textTrackModuleRef,
+ textTrackSurfaceImplementationDigests,
} from "./index.js";
export const svmlPackage = {
@@ -9,9 +15,23 @@ export const svmlPackage = {
name: "@narratage/text-track",
modules: [{ manifest: textTrackManifest, specifiers: ["@narratage/text-track", "@narratage/text-track@1"] }],
components: [textTrackComponent],
- hostFacets: [createTextSurfaceHostFacet({
- module: textTrackModuleRef, surface: "track", mode: "structured",
- implementationDigest: textTrackSurfaceImplementationDigest, handler: decodeTextTrackSurface,
- })],
+ hostFacets: [
+ createTextSurfaceHostFacet({
+ module: textTrackModuleRef, surface: "style", mode: "structured",
+ implementationDigest: textTrackSurfaceImplementationDigests.style, handler: decodeTextStyleSurface,
+ }),
+ createTextSurfaceHostFacet({
+ module: textTrackModuleRef, surface: "motion", mode: "structured",
+ implementationDigest: textTrackSurfaceImplementationDigests.motion, handler: decodeTextMotionSurface,
+ }),
+ createTextSurfaceHostFacet({
+ module: textTrackModuleRef, surface: "track", mode: "structured",
+ implementationDigest: textTrackSurfaceImplementationDigests.track, handler: decodeTextTrackSurface,
+ }),
+ createTextSurfaceHostFacet({
+ module: textTrackModuleRef, surface: "mask", mode: "structured",
+ implementationDigest: textTrackSurfaceImplementationDigests.mask, handler: decodeTextMaskSurface,
+ }),
+ ],
};
export default svmlPackage;
diff --git a/packages/text-track/src/component.ts b/packages/text-track/src/component.ts
index d4dc58a6..fbf18cc3 100644
--- a/packages/text-track/src/component.ts
+++ b/packages/text-track/src/component.ts
@@ -1,101 +1,144 @@
import type { ComponentPackage } from "@narratage/component-kit";
-import type { NarrativeSelection, NarrativeSelectionRef } from "@narratage/narrative";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
import type { ProgramSpace } from "@narratage/program-space";
import type { CompleteSemanticMap } from "@narratage/semantic-map";
-import type { SpatialFrame } from "@narratage/spatial";
+import type { CompositableSurfaceRef } from "@narratage/media";
+import type { SpatialFrame, SpatialPath, SpatialPoint } from "@narratage/spatial";
import type { StoredValue } from "@narratage/protocol";
import { canonicalize } from "@narratage/protocol";
import { textTrackProducers } from "./manifest.js";
import {
- appendFullTextItem,
- appendFullTextItemImplementationDigest,
- appendSelectedTextItem,
- appendSelectedTextItemImplementationDigest,
- compileTextTrackImplementationDigest,
- compileTextTrackProgram,
+ appendMomentTextItem,
+ appendProgramTextItem,
+ appendSelectionTextItem,
+ bindAreaTextPlacement,
+ bindAreaTextPlacementImplementationDigest,
+ bindPathTextPlacement,
+ bindPathTextPlacementImplementationDigest,
+ bindPointTextPlacement,
+ bindPointTextPlacementImplementationDigest,
createTextTrackSet,
createTextTrackSetImplementationDigest,
finalizeTextTrack,
finalizeTextTrackImplementationDigest,
renderTextTrack,
renderTextTrackImplementationDigest,
+ renderTextMaskTrack,
+ renderTextMaskTrackImplementationDigest,
+ appendMomentTextItemImplementationDigest,
+ appendProgramTextItemImplementationDigest,
+ appendSelectionTextItemImplementationDigest,
} from "./program.js";
import type {
TextItemSpec,
+ TextPlacement,
+ TextMotion,
+ TextMaskSpec,
+ TextStyle,
TextTrackHeader,
TextTrackProgram,
TextTrackSet,
- TextTrackSpec,
} from "./types.js";
function inline<T>(value: StoredValue | undefined, subject: string): T {
- if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline.`);
return value.value as unknown as T;
}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
export const textTrackComponent = {
name: "@narratage/text-track",
- producers: [{
- producer: textTrackProducers.createSet,
- implementationDigest: createTextTrackSetImplementationDigest,
- handler: () => ({
- outputs: { set: { kind: "inline", value: canonicalize(createTextTrackSet()) } }, needs: {},
- }),
- }, {
- producer: textTrackProducers.appendFull,
- implementationDigest: appendFullTextItemImplementationDigest,
- handler: ({ inputs }) => ({
- outputs: { set: { kind: "inline", value: canonicalize(appendFullTextItem(
+ producers: [
+ {
+ producer: textTrackProducers.bindPoint,
+ implementationDigest: bindPointTextPlacementImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindPointTextPlacement(inline<SpatialPoint>(inputs.point?.value, "SpatialPoint"))) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.bindArea,
+ implementationDigest: bindAreaTextPlacementImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindAreaTextPlacement(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"))) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.bindPath,
+ implementationDigest: bindPathTextPlacementImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindPathTextPlacement(inline<SpatialPath>(inputs.path?.value, "SpatialPath"))) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.createSet,
+ implementationDigest: createTextTrackSetImplementationDigest,
+ handler: () => ({ outputs: { set: output(createTextTrackSet()) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.appendProgram,
+ implementationDigest: appendProgramTextItemImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendProgramTextItem(
inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),
inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
- inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),
inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
- )) } }, needs: {},
- }),
- }, {
- producer: textTrackProducers.appendSelected,
- implementationDigest: appendSelectedTextItemImplementationDigest,
- handler: ({ inputs }) => ({
- outputs: { set: { kind: "inline", value: canonicalize(appendSelectedTextItem(
+ inline<TextStyle>(inputs.style?.value, "TextStyle"),
+ inline<TextMotion>(inputs.motion?.value, "TextMotion"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.appendSelection,
+ implementationDigest: appendSelectionTextItemImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendSelectionTextItem(
inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),
inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),
inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
- inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),
inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
- )) } }, needs: {},
- }),
- }, {
- producer: textTrackProducers.finalize,
- implementationDigest: finalizeTextTrackImplementationDigest,
- handler: ({ inputs }) => ({
- outputs: { program: { kind: "inline", value: canonicalize(finalizeTextTrack(
+ inline<TextStyle>(inputs.style?.value, "TextStyle"),
+ inline<TextMotion>(inputs.motion?.value, "TextMotion"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.appendMoment,
+ implementationDigest: appendMomentTextItemImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendMomentTextItem(
+ inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),
+ inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),
+ inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
+ inline<TextStyle>(inputs.style?.value, "TextStyle"),
+ inline<TextMotion>(inputs.motion?.value, "TextMotion"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.finalize,
+ implementationDigest: finalizeTextTrackImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { program: output(finalizeTextTrack(
inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),
inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),
- )) } }, needs: {},
- }),
- }, {
- producer: textTrackProducers.compile,
- implementationDigest: compileTextTrackImplementationDigest,
- handler: ({ inputs }) => ({
- outputs: { program: { kind: "inline", value: canonicalize(compileTextTrackProgram(
+ )) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.render,
+ implementationDigest: renderTextTrackImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { track: output(renderTextTrack(
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
- inline<TextTrackSpec>(inputs.spec?.value, "TextTrackSpec"),
- )) } },
- needs: {},
- }),
- }, {
- producer: textTrackProducers.render,
- implementationDigest: renderTextTrackImplementationDigest,
- handler: ({ inputs }) => ({
- outputs: { track: { kind: "inline", value: canonicalize(renderTextTrack(
+ inline<TextTrackProgram>(inputs.program?.value, "TextTrackProgram"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: textTrackProducers.renderMask,
+ implementationDigest: renderTextMaskTrackImplementationDigest,
+ handler: ({ inputs }) => ({ outputs: { track: output(renderTextMaskTrack(
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
inline<TextTrackProgram>(inputs.program?.value, "TextTrackProgram"),
- )) } },
- needs: {},
- }),
- }],
+ inline<CompositableSurfaceRef>(inputs.material?.value, "CompositableSurfaceRef"),
+ inline<TextMaskSpec>(inputs.spec?.value, "TextMaskSpec"),
+ )) }, needs: {} }),
+ },
+ ],
} satisfies ComponentPackage;
diff --git a/packages/text-track/src/index.ts b/packages/text-track/src/index.ts
index 3bccb82d..e76b28f2 100644
--- a/packages/text-track/src/index.ts
+++ b/packages/text-track/src/index.ts
@@ -6,16 +6,27 @@ export {
textTrackModuleRef,
textTrackProducers,
textTrackProgramSchema,
- textTrackSpecSchema,
- textTrackSurfaceImplementationDigest,
+ textTrackSurfaceImplementationDigests,
textTrackTypes,
} from "./manifest.js";
export {
- appendFullTextItem,
- appendFullTextItemImplementationDigest,
- appendSelectedTextItem,
- appendSelectedTextItemImplementationDigest,
+ appendMomentTextItem,
+ appendMomentTextItemImplementationDigest,
+ appendProgramTextItem,
+ appendProgramTextItemImplementationDigest,
+ appendSelectionTextItem,
+ appendSelectionTextItemImplementationDigest,
+ bindAreaTextPlacement,
+ bindAreaTextPlacementImplementationDigest,
+ bindPathTextPlacement,
+ bindPathTextPlacementImplementationDigest,
+ bindPointTextPlacement,
+ bindPointTextPlacementImplementationDigest,
assertTextItemSpec,
+ assertTextMaskSpec,
+ assertTextMotion,
+ assertTextPlacement,
+ assertTextStyle,
assertTextTrackHeader,
assertTextTrackProgramIdentity,
assertTextTrackSet,
@@ -23,15 +34,23 @@ export {
createTextTrackSetImplementationDigest,
finalizeTextTrack,
finalizeTextTrackImplementationDigest,
- assertTextTrackSpec,
- compileTextTrackImplementationDigest,
- compileTextTrackProgram,
renderTextTrack,
renderTextTrackImplementationDigest,
+ renderTextMaskTrack,
+ renderTextMaskTrackImplementationDigest,
sealTextTrackProgram,
sealTextTrackHeader,
sealTextItemSpec,
- sealTextTrackSpec,
+ sealTextMotion,
+ sealTextMaskSpec,
+ sealTextPlacement,
+ sealTextStyle,
+ stillTextMotion,
} from "./program.js";
-export { decodeTextTrackSurface } from "./surface.js";
+export {
+ decodeTextMotionSurface,
+ decodeTextStyleSurface,
+ decodeTextTrackSurface,
+ decodeTextMaskSurface,
+} from "./surface.js";
export type * from "./types.js";
diff --git a/packages/text-track/src/manifest.ts b/packages/text-track/src/manifest.ts
index 0fab46d9..6e4c22c5 100644
--- a/packages/text-track/src/manifest.ts
+++ b/packages/text-track/src/manifest.ts
@@ -1,203 +1,208 @@
import { narrativeDependency, narrativeTypes } from "@narratage/narrative";
import { programSpaceDependency, programSpaceTypes } from "@narratage/program-space";
import { semanticMapDependency, semanticMapTypes } from "@narratage/semantic-map";
-import { compositionDependency, compositionTypes } from "@narratage/composition";
-import { spatialDependency, spatialTypes, spatialFrameSchema } from "@narratage/spatial";
-import type { Track } from "@narratage/composition";
+import {
+ compositionDependency,
+ compositionTypes,
+ visualTextDocumentSchema,
+ visualTextFlowSchema,
+ visualTextPaintSchema,
+ visualTextSequenceSchema,
+ visualTextTypographySchema,
+} from "@narratage/composition";
+import {
+ spatialDependency,
+ spatialFrameSchema,
+ spatialPathSchema,
+ spatialPointSchema,
+ spatialTypes,
+} from "@narratage/spatial";
+import { VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "@narratage/visual-ir";
+import { mediaDependency, mediaTypes } from "@narratage/media";
import { digestOf } from "@narratage/protocol";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
import {
- appendFullTextItemImplementationDigest,
- appendSelectedTextItemImplementationDigest,
- compileTextTrackImplementationDigest,
+ appendMomentTextItemImplementationDigest,
+ appendProgramTextItemImplementationDigest,
+ appendSelectionTextItemImplementationDigest,
+ bindAreaTextPlacementImplementationDigest,
+ bindPathTextPlacementImplementationDigest,
+ bindPointTextPlacementImplementationDigest,
createTextTrackSetImplementationDigest,
finalizeTextTrackImplementationDigest,
renderTextTrackImplementationDigest,
+ renderTextMaskTrackImplementationDigest,
} from "./program.js";
export const textTrackModuleRef = { name: "@narratage/text-track", version: "0.0.0-dev" } as const;
export const textTrackTypes = {
+ style: { module: textTrackModuleRef, name: "TextStyle" },
+ motion: { module: textTrackModuleRef, name: "TextMotion" },
+ placement: { module: textTrackModuleRef, name: "TextPlacement" },
program: { module: textTrackModuleRef, name: "TextTrackProgram" },
- spec: { module: textTrackModuleRef, name: "TextTrackSpec" },
header: { module: textTrackModuleRef, name: "TextTrackHeader" },
itemSpec: { module: textTrackModuleRef, name: "TextItemSpec" },
set: { module: textTrackModuleRef, name: "TextTrackSet" },
+ maskSpec: { module: textTrackModuleRef, name: "TextMaskSpec" },
} satisfies Record<string, TypeRef>;
+
export const textTrackProducers = {
- compile: { module: textTrackModuleRef, name: "compile-text-track" },
- render: { module: textTrackModuleRef, name: "render-text-track" },
+ bindPoint: { module: textTrackModuleRef, name: "bind-point-placement" },
+ bindArea: { module: textTrackModuleRef, name: "bind-area-placement" },
+ bindPath: { module: textTrackModuleRef, name: "bind-path-placement" },
createSet: { module: textTrackModuleRef, name: "create-text-track-set" },
- appendFull: { module: textTrackModuleRef, name: "append-full-text-item" },
- appendSelected: { module: textTrackModuleRef, name: "append-selected-text-item" },
+ appendProgram: { module: textTrackModuleRef, name: "append-program-text-item" },
+ appendSelection: { module: textTrackModuleRef, name: "append-selection-text-item" },
+ appendMoment: { module: textTrackModuleRef, name: "append-moment-text-item" },
finalize: { module: textTrackModuleRef, name: "finalize-text-track" },
+ render: { module: textTrackModuleRef, name: "render-text-track" },
+ renderMask: { module: textTrackModuleRef, name: "render-text-mask-track" },
} satisfies Record<string, ProducerRef>;
const string = { kind: "string", minLength: 1 } as const;
const number = { kind: "number" } as const;
-const positiveNumber = { kind: "number", minimum: 0.000001 } as const;
-const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const positive = { kind: "number", minimum: 0.000001 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
const signedInteger = { kind: "number", integer: true } as const;
-const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({
- kind: "object",
- fields,
-});
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const enumString = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
+
+const duration: ValueSchema = { kind: "oneOf", variants: [
+ object({ unit: { schema: { kind: "literal", value: "frames" } }, value: { schema: integer } }),
+ object({ unit: { schema: { kind: "literal", value: "milliseconds" } }, value: { schema: number } }),
+ object({ unit: { schema: { kind: "literal", value: "seconds" } }, numerator: { schema: signedInteger }, denominator: { schema: positiveInteger } }),
+] };
+const point: ValueSchema = { kind: "oneOf", variants: [
+ ...["program.start", "program.end", "selection.start", "selection.end", "moment.cue"].map((ref) => object({ ref: { schema: { kind: "literal", value: ref } }, offset: { schema: duration, optional: true } })),
+ object({ ref: { schema: { kind: "literal", value: "absolute" } }, at: { schema: duration } }),
+] };
+const projection = object({ start: { schema: point }, end: { schema: point } });
+const expansion: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "one" } } }),
+ object({ kind: { schema: { kind: "literal", value: "each" } } }),
+] };
-const textAppearanceSchema = object({
- color: { schema: string },
- fontSizePx: { schema: positiveNumber },
- fontFamily: { schema: string, optional: true },
- fontWeight: { schema: { kind: "number", integer: true, minimum: 1, maximum: 1000 }, optional: true },
- lineHeight: { schema: positiveNumber, optional: true },
- align: { schema: { kind: "string", enum: ["left", "center", "right"] }, optional: true },
- verticalAlign: { schema: { kind: "string", enum: ["top", "center", "bottom"] }, optional: true },
- backgroundColor: { schema: string, optional: true },
- borderRadiusPx: { schema: { kind: "number", minimum: 0 }, optional: true },
- paddingPx: { schema: { kind: "number", minimum: 0 }, optional: true },
- letterSpacingPx: { schema: number, optional: true },
+const styleDeclaration: ValueSchema = { kind: "oneOf", variants: VISUAL_STYLE_NAMES_V1.map((name) => object({
+ name: { schema: { kind: "literal", value: name } },
+ value: { schema: Object.hasOwn(VISUAL_STYLE_ENUM_VALUES_V1, name)
+ ? { kind: "string", enum: VISUAL_STYLE_ENUM_VALUES_V1[name as keyof typeof VISUAL_STYLE_ENUM_VALUES_V1] }
+ : { kind: "oneOf", variants: [{ kind: "string" }, { kind: "number" }] } },
+})) };
+const visualKeyframe = object({
+ atFrame: { schema: integer },
+ easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true },
+ style: { schema: { kind: "array", minItems: 1, items: styleDeclaration } },
});
+const visualAnimation = object({ keyframes: { schema: { kind: "array", minItems: 2, items: visualKeyframe } } });
+
+const areaFlow = (() => {
+ const schema = visualTextFlowSchema;
+ if (schema.kind !== "object") throw new Error("Visual Text flow schema must be an object.");
+ const { form: _form, ...fields } = schema.fields;
+ return object(fields);
+})();
-const textItemSchema = object({
- id: { schema: string },
- text: { schema: string },
- span: { schema: object({
- startFrame: { schema: unsignedInteger },
- endFrameExclusive: { schema: unsignedInteger },
+export const textStyleSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-style@1" } },
+ id: { schema: string }, stackingOrder: { schema: signedInteger },
+ typography: { schema: visualTextTypographySchema },
+ paints: { schema: { kind: "array", items: visualTextPaintSchema } },
+ area: { schema: areaFlow },
+ point: { schema: object({ anchorInline: { schema: enumString(["start", "center", "end"]) }, anchorBlock: { schema: enumString(["start", "center", "end"]) } }) },
+ path: { schema: object({
+ side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) },
+ startMarginPx: { schema: { kind: "number", minimum: 0 } }, endMarginPx: { schema: { kind: "number", minimum: 0 } },
+ align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: { kind: "boolean" } },
+ overflow: { schema: enumString(["visible", "clip"]) },
}) },
- z: { schema: signedInteger },
- tieBreak: { schema: string },
- frame: { schema: spatialFrameSchema },
- appearance: { schema: textAppearanceSchema },
});
-export const textTrackProgramSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.text-track-program@1" } },
- id: { schema: string },
- items: { schema: { kind: "array", minItems: 1, items: textItemSchema } },
+export const textMotionSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-motion@1" } }, id: { schema: string },
+ item: { schema: visualAnimation, optional: true },
+ sequences: { schema: { kind: "array", items: visualTextSequenceSchema } },
+ pathMargin: { schema: object({ keyframes: { schema: { kind: "array", minItems: 2, items: object({
+ atFrame: { schema: integer }, startMarginPx: { schema: { kind: "number", minimum: 0 } },
+ easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true },
+ }) } } }), optional: true },
});
-export const textTrackSpecSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.text-track-spec@1" } },
- id: { schema: string },
- items: { schema: { kind: "array", minItems: 1, items: object({
- id: { schema: string },
- text: { schema: string },
- during: { schema: { kind: "literal", value: "full" } },
- z: { schema: signedInteger },
- frame: { schema: spatialFrameSchema },
- appearance: { schema: textAppearanceSchema },
- }) } },
+const geometry: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "point" } }, point: { schema: spatialPointSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "area" } }, frame: { schema: spatialFrameSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "path" } }, path: { schema: spatialPathSchema } }),
+] };
+export const textPlacementSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-placement@1" } }, geometry: { schema: geometry },
});
-
-const textTrackHeaderSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.text-track-header@1" } },
- id: { schema: string },
+export const textItemSpecSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-item-spec@1" } }, id: { schema: string },
+ document: { schema: visualTextDocumentSchema },
+ projection: { schema: projection }, expansion: { schema: expansion },
});
-
-const textItemSpecSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.text-item-spec@1" } },
- id: { schema: string },
- text: { schema: string },
- z: { schema: signedInteger },
- appearance: { schema: textAppearanceSchema },
+const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: positiveInteger } });
+const item = object({
+ id: { schema: string }, sourceOccurrenceId: { schema: string }, span: { schema: span }, geometry: { schema: geometry },
+ document: { schema: visualTextDocumentSchema }, style: { schema: textStyleSchema }, motion: { schema: textMotionSchema },
+ tieBreak: { schema: string },
});
-
-const textTrackSetSchema: ValueSchema = object({
- contract: { schema: { kind: "literal", value: "svml.text-track-set@1" } },
- items: { schema: { kind: "array", items: textItemSchema } },
+export const textTrackProgramSchema: ValueSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-track-program@1" } }, id: { schema: string },
+ items: { schema: { kind: "array", minItems: 1, items: item } },
});
+const textTrackHeaderSchema = object({ contract: { schema: { kind: "literal", value: "svml.text-track-header@1" } }, id: { schema: string } });
+const textTrackSetSchema = object({ contract: { schema: { kind: "literal", value: "svml.text-track-set@1" } }, items: { schema: { kind: "array", items: item } } });
+const textMaskSpecSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.text-mask-spec@1" } },
+ id: { schema: string }, mode: { schema: enumString(["alpha", "luminance"]) },
+ materialFit: { schema: enumString(["contain", "cover", "fill"]) },
+});
+
+export const textTrackSurfaceImplementationDigests = {
+ style: digestOf("@narratage/text-track/style-surface@1"),
+ motion: digestOf("@narratage/text-track/motion-surface@1"),
+ track: digestOf("@narratage/text-track/complete-track-surface@1"),
+ mask: digestOf("@narratage/text-track/owned-mask-surface@1"),
+} as const;
-export const textTrackSurfaceImplementationDigest = digestOf("@narratage/text-track/track-surface@1");
+const registered = (locator: string, digest: ReturnType<typeof digestOf>) => ({ kind: "registered" as const, locator, digest });
export const textTrackManifest: ModuleManifest = {
format: "svml.module@1",
name: textTrackModuleRef.name,
version: textTrackModuleRef.version,
- dependencies: [
- programSpaceDependency,
- narrativeDependency,
- semanticMapDependency,
- spatialDependency,
- compositionDependency,
- ],
+ dependencies: [programSpaceDependency, narrativeDependency, semanticMapDependency, spatialDependency, mediaDependency, compositionDependency],
types: [
+ { name: textTrackTypes.style.name, schema: textStyleSchema },
+ { name: textTrackTypes.motion.name, schema: textMotionSchema },
+ { name: textTrackTypes.placement.name, schema: textPlacementSchema },
{ name: textTrackTypes.program.name, schema: textTrackProgramSchema },
- { name: textTrackTypes.spec.name, schema: textTrackSpecSchema },
{ name: textTrackTypes.header.name, schema: textTrackHeaderSchema },
{ name: textTrackTypes.itemSpec.name, schema: textItemSpecSchema },
{ name: textTrackTypes.set.name, schema: textTrackSetSchema },
+ { name: textTrackTypes.maskSpec.name, schema: textMaskSpecSchema },
],
capabilities: [],
- surfaces: [{
- name: "track", tag: "Track", mode: "structured",
- outputs: [textTrackTypes.spec, textTrackTypes.header, textTrackTypes.itemSpec,
- textTrackTypes.set, textTrackTypes.program, compositionTypes.visualTrack],
- implementation: { kind: "trusted-frontend-surface", locator: "@narratage/text-track/track-surface", digest: textTrackSurfaceImplementationDigest },
- }],
- producers: [{
- name: textTrackProducers.createSet.name,
- inputs: [],
- outputs: [{ name: "set", type: textTrackTypes.set }],
- needs: [],
- implementation: { kind: "registered", locator: "@narratage/text-track/create-set", digest: createTextTrackSetImplementationDigest },
- }, {
- name: textTrackProducers.appendFull.name,
- inputs: [
- { name: "set", type: textTrackTypes.set },
- { name: "header", type: textTrackTypes.header },
- { name: "space", type: programSpaceTypes.programSpace },
- { name: "frame", type: spatialTypes.frame },
- { name: "spec", type: textTrackTypes.itemSpec },
- ],
- outputs: [{ name: "set", type: textTrackTypes.set }],
- needs: [],
- implementation: { kind: "registered", locator: "@narratage/text-track/append-full", digest: appendFullTextItemImplementationDigest },
- }, {
- name: textTrackProducers.appendSelected.name,
- inputs: [
- { name: "set", type: textTrackTypes.set },
- { name: "header", type: textTrackTypes.header },
- { name: "map", type: semanticMapTypes.complete },
- { name: "selection", type: narrativeTypes.selection },
- { name: "space", type: programSpaceTypes.programSpace },
- { name: "frame", type: spatialTypes.frame },
- { name: "spec", type: textTrackTypes.itemSpec },
- ],
- outputs: [{ name: "set", type: textTrackTypes.set }],
- needs: [],
- implementation: { kind: "registered", locator: "@narratage/text-track/append-selected", digest: appendSelectedTextItemImplementationDigest },
- }, {
- name: textTrackProducers.finalize.name,
- inputs: [
- { name: "header", type: textTrackTypes.header },
- { name: "set", type: textTrackTypes.set },
- ],
- outputs: [{ name: "program", type: textTrackTypes.program }],
- needs: [],
- implementation: { kind: "registered", locator: "@narratage/text-track/finalize", digest: finalizeTextTrackImplementationDigest },
- }, {
- name: textTrackProducers.compile.name,
- inputs: [
- { name: "space", type: programSpaceTypes.programSpace },
- { name: "spec", type: textTrackTypes.spec },
- ],
- outputs: [{ name: "program", type: textTrackTypes.program }],
- needs: [],
- implementation: { kind: "registered", locator: "@narratage/text-track/compile", digest: compileTextTrackImplementationDigest },
- }, {
- name: textTrackProducers.render.name,
- inputs: [
- { name: "space", type: programSpaceTypes.programSpace },
- { name: "program", type: textTrackTypes.program },
- ],
- outputs: [{ name: "track", type: compositionTypes.visualTrack }],
- needs: [],
- implementation: {
- kind: "registered",
- locator: "@narratage/text-track/render",
- digest: renderTextTrackImplementationDigest,
- },
- }],
+ surfaces: [
+ { name: "style", tag: "Style", mode: "structured", outputs: [textTrackTypes.style], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/text-track/style-surface", digest: textTrackSurfaceImplementationDigests.style } },
+ { name: "motion", tag: "Motion", mode: "structured", outputs: [textTrackTypes.motion], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/text-track/motion-surface", digest: textTrackSurfaceImplementationDigests.motion } },
+ { name: "track", tag: "Track", mode: "structured", outputs: [textTrackTypes.header, textTrackTypes.itemSpec, textTrackTypes.motion, textTrackTypes.set, textTrackTypes.placement, textTrackTypes.program, compositionTypes.visualTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/text-track/complete-track-surface", digest: textTrackSurfaceImplementationDigests.track } },
+ { name: "mask", tag: "Mask", mode: "structured", outputs: [textTrackTypes.maskSpec, compositionTypes.visualTrack], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/text-track/owned-mask-surface", digest: textTrackSurfaceImplementationDigests.mask } },
+ ],
+ producers: [
+ { name: textTrackProducers.bindPoint.name, inputs: [{ name: "point", type: spatialTypes.point }], outputs: [{ name: "placement", type: textTrackTypes.placement }], needs: [], implementation: registered("@narratage/text-track/bind-point-placement", bindPointTextPlacementImplementationDigest) },
+ { name: textTrackProducers.bindArea.name, inputs: [{ name: "frame", type: spatialTypes.frame }], outputs: [{ name: "placement", type: textTrackTypes.placement }], needs: [], implementation: registered("@narratage/text-track/bind-area-placement", bindAreaTextPlacementImplementationDigest) },
+ { name: textTrackProducers.bindPath.name, inputs: [{ name: "path", type: spatialTypes.path }], outputs: [{ name: "placement", type: textTrackTypes.placement }], needs: [], implementation: registered("@narratage/text-track/bind-path-placement", bindPathTextPlacementImplementationDigest) },
+ { name: textTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: textTrackTypes.set }], needs: [], implementation: registered("@narratage/text-track/create-set", createTextTrackSetImplementationDigest) },
+ { name: textTrackProducers.appendProgram.name, inputs: [{ name: "set", type: textTrackTypes.set }, { name: "header", type: textTrackTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "placement", type: textTrackTypes.placement }, { name: "spec", type: textTrackTypes.itemSpec }, { name: "style", type: textTrackTypes.style }, { name: "motion", type: textTrackTypes.motion }], outputs: [{ name: "set", type: textTrackTypes.set }], needs: [], implementation: registered("@narratage/text-track/append-program", appendProgramTextItemImplementationDigest) },
+ { name: textTrackProducers.appendSelection.name, inputs: [{ name: "set", type: textTrackTypes.set }, { name: "header", type: textTrackTypes.header }, { name: "map", type: semanticMapTypes.complete }, { name: "selection", type: narrativeTypes.selection }, { name: "space", type: programSpaceTypes.programSpace }, { name: "placement", type: textTrackTypes.placement }, { name: "spec", type: textTrackTypes.itemSpec }, { name: "style", type: textTrackTypes.style }, { name: "motion", type: textTrackTypes.motion }], outputs: [{ name: "set", type: textTrackTypes.set }], needs: [], implementation: registered("@narratage/text-track/append-selection", appendSelectionTextItemImplementationDigest) },
+ { name: textTrackProducers.appendMoment.name, inputs: [{ name: "set", type: textTrackTypes.set }, { name: "header", type: textTrackTypes.header }, { name: "map", type: semanticMapTypes.complete }, { name: "moment", type: narrativeTypes.moment }, { name: "space", type: programSpaceTypes.programSpace }, { name: "placement", type: textTrackTypes.placement }, { name: "spec", type: textTrackTypes.itemSpec }, { name: "style", type: textTrackTypes.style }, { name: "motion", type: textTrackTypes.motion }], outputs: [{ name: "set", type: textTrackTypes.set }], needs: [], implementation: registered("@narratage/text-track/append-moment", appendMomentTextItemImplementationDigest) },
+ { name: textTrackProducers.finalize.name, inputs: [{ name: "header", type: textTrackTypes.header }, { name: "set", type: textTrackTypes.set }], outputs: [{ name: "program", type: textTrackTypes.program }], needs: [], implementation: registered("@narratage/text-track/finalize", finalizeTextTrackImplementationDigest) },
+ { name: textTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: textTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [], implementation: registered("@narratage/text-track/render", renderTextTrackImplementationDigest) },
+ { name: textTrackProducers.renderMask.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: textTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: textTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [], implementation: registered("@narratage/text-track/render-mask", renderTextMaskTrackImplementationDigest) },
+ ],
};
export const textTrackManifestDigest = digestOf(textTrackManifest);
diff --git a/packages/text-track/src/program.ts b/packages/text-track/src/program.ts
index c7129126..c50fdead 100644
--- a/packages/text-track/src/program.ts
+++ b/packages/text-track/src/program.ts
@@ -1,381 +1,684 @@
-import type { NarrativeSelectionRef } from "@narratage/narrative";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";
import type { ProgramSpace } from "@narratage/program-space";
-import { assertCompleteSemanticMapIdentity, assertNarrativeSelectionIdentity } from "@narratage/semantic-map";
+import {
+ assertCompleteSemanticMapIdentity,
+ assertNarrativeMomentIdentity,
+ assertNarrativeSelectionIdentity,
+} from "@narratage/semantic-map";
import type { CompleteSemanticMap } from "@narratage/semantic-map";
-import { assertSpatialFrame } from "@narratage/spatial";
-import type { SpatialFrame } from "@narratage/spatial";
+import {
+ assertSpatialFrame,
+ assertSpatialPath,
+ assertSpatialPoint,
+} from "@narratage/spatial";
+import type { SpatialFrame, SpatialPath, SpatialPoint } from "@narratage/spatial";
import {
assertWindowRelation,
+ projectMomentWindows,
projectProgramWindow,
projectSelectionWindows,
} from "@narratage/temporal";
-import { assertVisualTrackIdentity, sealVisualTrack } from "@narratage/composition";
-import type { VisualStyleDeclaration, VisualTrack } from "@narratage/composition";
+import type { ProjectedOccurrence } from "@narratage/temporal";
+import {
+ assertVisualTrackIdentity,
+ sealVisualTrack,
+} from "@narratage/composition";
+import type {
+ VisualElement,
+ VisualPathTextElement,
+ VisualStyleDeclaration,
+ VisualTextElement,
+ VisualTextFlowElement,
+ VisualTrack,
+} from "@narratage/composition";
+import { assertCompositableSurfaceRef } from "@narratage/media";
+import type { CompositableSurfaceRef } from "@narratage/media";
import { canonicalize, digestOf } from "@narratage/protocol";
import type {
- TextAppearance,
+ TextGeometry,
TextItem,
TextItemSpec,
+ TextMotion,
+ TextMaskSpec,
+ TextPlacement,
+ TextStyle,
TextTrackHeader,
TextTrackProgram,
TextTrackSet,
- TextTrackSpec,
} from "./types.js";
-export const renderTextTrackImplementationDigest = digestOf("@narratage/text-track/render@1");
-export const compileTextTrackImplementationDigest = digestOf("@narratage/text-track/compile@1");
-export const createTextTrackSetImplementationDigest = digestOf("@narratage/text-track/create-set@1");
-export const appendFullTextItemImplementationDigest = digestOf("@narratage/text-track/append-full-item@1");
-export const appendSelectedTextItemImplementationDigest = digestOf("@narratage/text-track/append-selected-item@1");
-export const finalizeTextTrackImplementationDigest = digestOf("@narratage/text-track/finalize@1");
+export const renderTextTrackImplementationDigest = digestOf("@narratage/text-track/render-complete@1");
+export const renderTextMaskTrackImplementationDigest = digestOf("@narratage/text-track/render-owned-mask@1");
+export const createTextTrackSetImplementationDigest = digestOf("@narratage/text-track/create-set-complete@1");
+export const appendProgramTextItemImplementationDigest = digestOf("@narratage/text-track/append-program-item@1");
+export const appendSelectionTextItemImplementationDigest = digestOf("@narratage/text-track/append-selection-item@1");
+export const appendMomentTextItemImplementationDigest = digestOf("@narratage/text-track/append-moment-item@1");
+export const finalizeTextTrackImplementationDigest = digestOf("@narratage/text-track/finalize-complete@1");
+export const bindPointTextPlacementImplementationDigest = digestOf("@narratage/text-track/bind-point-placement@1");
+export const bindAreaTextPlacementImplementationDigest = digestOf("@narratage/text-track/bind-area-placement@1");
+export const bindPathTextPlacementImplementationDigest = digestOf("@narratage/text-track/bind-path-placement@1");
-function assertNonEmpty(value: string, label: string): void {
+function nonEmpty(value: string, label: string): void {
if (!value.trim()) throw new Error(`${label} must not be empty.`);
}
-function assertFinite(value: number, label: string): void {
+function finite(value: number, label: string): void {
if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
}
-function normalizeItem(item: TextItem): TextItem {
- return {
- id: item.id,
- text: item.text,
- span: { ...item.span },
- z: item.z,
- tieBreak: item.tieBreak,
- frame: { ...item.frame },
- appearance: { ...item.appearance },
- };
-}
-
-function textTrackProgramContent(value: TextTrackProgram): TextTrackProgram {
- return {
- contract: "svml.text-track-program@1",
- id: value.id,
- items: [...value.items]
- .map(normalizeItem)
- .sort((left, right) => left.span.startFrame - right.span.startFrame
- || left.z - right.z
- || left.tieBreak.localeCompare(right.tieBreak)
- || left.id.localeCompare(right.id)),
- };
+function assertDocument(document: TextItemSpec["document"], label: string): void {
+ if (document.paragraphs.length === 0) throw new Error(`${label} requires a paragraph.`);
+ const ids = new Set<string>();
+ let visible = false;
+ for (const paragraph of document.paragraphs) {
+ nonEmpty(paragraph.id, `${label} paragraph id`);
+ if (ids.has(paragraph.id) || paragraph.inlines.length === 0) throw new Error(`${label} has an invalid paragraph.`);
+ ids.add(paragraph.id);
+ for (const inline of paragraph.inlines) {
+ nonEmpty(inline.id, `${label} inline id`);
+ if (ids.has(inline.id)) throw new Error(`${label} repeats ${inline.id}.`);
+ ids.add(inline.id);
+ if (inline.kind === "text") {
+ if (inline.text.length === 0) throw new Error(`${label} has an empty text run.`);
+ visible ||= inline.text.trim().length > 0;
+ }
+ }
+ }
+ if (!visible) throw new Error(`${label} contains no visible text.`);
}
-export function sealTextTrackProgram(value: TextTrackProgram): TextTrackProgram {
- return textTrackProgramContent(value);
-}
-
-function assertAppearance(appearance: TextAppearance, label: string): void {
- assertNonEmpty(appearance.color, `${label} color`);
- assertFinite(appearance.fontSizePx, `${label} fontSizePx`);
- if (appearance.fontSizePx <= 0) throw new Error(`${label} fontSizePx must be positive.`);
- if (appearance.fontFamily !== undefined) assertNonEmpty(appearance.fontFamily, `${label} fontFamily`);
- if (
- appearance.fontWeight !== undefined
- && (!Number.isSafeInteger(appearance.fontWeight) || appearance.fontWeight < 1 || appearance.fontWeight > 1000)
- ) {
- throw new Error(`${label} fontWeight must be an integer from 1 to 1000.`);
+export function assertTextStyle(style: TextStyle): void {
+ if (style.contract !== "svml.text-style@1") throw new Error("Unsupported TextStyle contract.");
+ nonEmpty(style.id, "TextStyle id");
+ if (!Number.isSafeInteger(style.stackingOrder)) throw new Error("TextStyle stackingOrder must be a safe integer.");
+ finite(style.typography.sizePx, "TextStyle typography size");
+ if (style.typography.sizePx <= 0 || !Number.isSafeInteger(style.typography.weight)) {
+ throw new Error("TextStyle typography size or weight is invalid.");
+ }
+ if (style.typography.fonts === undefined) {
+ throw new Error("Official TextStyle requires an exact content-addressed font stack.");
}
- if (appearance.lineHeight !== undefined) {
- assertFinite(appearance.lineHeight, `${label} lineHeight`);
- if (appearance.lineHeight <= 0) throw new Error(`${label} lineHeight must be positive.`);
+ if (style.typography.prototypeFamily !== undefined) {
+ throw new Error("Official TextStyle does not accept an environment font family.");
}
- for (const [name, value] of Object.entries({
- borderRadiusPx: appearance.borderRadiusPx,
- paddingPx: appearance.paddingPx,
- })) {
- if (value !== undefined) {
- assertFinite(value, `${label} ${name}`);
- if (value < 0) throw new Error(`${label} ${name} must not be negative.`);
+ if (!["start", "center", "end"].includes(style.point.anchorInline)
+ || !["start", "center", "end"].includes(style.point.anchorBlock)
+ || !["left", "right"].includes(style.path.side)
+ || !["follow", "upright"].includes(style.path.orientation)
+ || !["start", "center", "end"].includes(style.path.align)
+ || !["visible", "clip"].includes(style.path.overflow)) {
+ throw new Error("TextStyle contains an unsupported Point or Path enum.");
+ }
+ if (style.area.overflow === "shrink") {
+ if (style.area.minimumScale === undefined || style.area.minimumScale <= 0 || style.area.minimumScale > 1) {
+ throw new Error("TextStyle shrink overflow requires minimumScale in (0, 1].");
}
+ } else if (style.area.minimumScale !== undefined) throw new Error("TextStyle minimumScale belongs only to shrink overflow.");
+ if (style.area.maxLines !== undefined && style.area.overflow !== "ellipsis" && style.area.overflow !== "shrink") {
+ throw new Error("TextStyle maxLines belongs only to ellipsis or shrink overflow.");
+ }
+ for (const value of [style.path.startMarginPx, style.path.endMarginPx]) {
+ finite(value, "TextStyle path margin");
+ if (value < 0) throw new Error("TextStyle path margins must not be negative.");
}
- if (appearance.backgroundColor !== undefined) assertNonEmpty(appearance.backgroundColor, `${label} backgroundColor`);
- if (appearance.letterSpacingPx !== undefined) assertFinite(appearance.letterSpacingPx, `${label} letterSpacingPx`);
+ assertVisualTrackIdentity({
+ contract: "svml.visual-track@1",
+ visualIr: "svml.visual-ir@1",
+ id: "text-style-validation",
+ presents: [{
+ id: "style",
+ span: { startFrame: 0, endFrameExclusive: 1 },
+ stacking: { order: style.stackingOrder, tieBreak: style.id },
+ elements: [
+ { id: "root", kind: "box", order: 0, style: [] },
+ {
+ id: "text", parent: "root", kind: "text-flow", order: 1, style: [],
+ document: { paragraphs: [{ id: "paragraph", inlines: [{ kind: "text", id: "run", text: "M" }] }] },
+ typography: style.typography,
+ paints: style.paints,
+ flow: { ...style.area, form: { kind: "area" } },
+ sequences: [],
+ },
+ ],
+ }],
+ });
}
-export function assertTextTrackProgramIdentity(program: TextTrackProgram, programSpace: ProgramSpace): void {
- assertProgramSpaceIdentity(programSpace);
- if (program.contract !== "svml.text-track-program@1") throw new Error("Unsupported TextTrackProgram contract.");
- assertNonEmpty(program.id, "TextTrackProgram id");
- if (program.items.length === 0) throw new Error("TextTrackProgram must contain at least one item.");
- const totalFrames = programSpaceFrameCount(programSpace);
+export function sealTextStyle(value: TextStyle): TextStyle {
+ const result = canonicalize(value) as unknown as TextStyle;
+ assertTextStyle(result);
+ return result;
+}
+
+export function assertTextMotion(motion: TextMotion): void {
+ if (motion.contract !== "svml.text-motion@1") throw new Error("Unsupported TextMotion contract.");
+ nonEmpty(motion.id, "TextMotion id");
const ids = new Set<string>();
- for (const item of program.items) {
- assertNonEmpty(item.id, "Text item id");
- if (ids.has(item.id)) throw new Error(`TextTrackProgram contains duplicate item ${item.id}.`);
- ids.add(item.id);
- if (!item.text) throw new Error(`${item.id} text must not be empty.`);
- if (
- !Number.isSafeInteger(item.span.startFrame)
- || !Number.isSafeInteger(item.span.endFrameExclusive)
- || item.span.startFrame < 0
- || item.span.endFrameExclusive <= item.span.startFrame
- || item.span.endFrameExclusive > totalFrames
- ) {
- throw new Error(`${item.id} span is outside ProgramSpace.`);
+ for (const sequence of motion.sequences) {
+ nonEmpty(sequence.id, "Text sequence id");
+ if (ids.has(sequence.id)) throw new Error(`TextMotion repeats sequence ${sequence.id}.`);
+ ids.add(sequence.id);
+ }
+ if (motion.pathMargin !== undefined) {
+ if (motion.pathMargin.keyframes.length < 2) throw new Error("Path-margin motion requires two keyframes.");
+ let previous = -1;
+ for (const keyframe of motion.pathMargin.keyframes) {
+ finite(keyframe.startMarginPx, "Path-margin start margin");
+ if (!Number.isSafeInteger(keyframe.atFrame)
+ || keyframe.atFrame <= previous
+ || keyframe.startMarginPx < 0
+ || (keyframe.easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing))) {
+ throw new Error("Path-margin motion keyframes are invalid.");
+ }
+ previous = keyframe.atFrame;
}
- if (!Number.isSafeInteger(item.z)) throw new Error(`${item.id} z must be a safe integer.`);
- assertNonEmpty(item.tieBreak, `${item.id} tieBreak`);
- assertSpatialFrame(item.frame);
- assertAppearance(item.appearance, `${item.id} appearance`);
}
}
-function rootStyle(item: TextItem): VisualStyleDeclaration[] {
- const vertical = item.appearance.verticalAlign ?? "center";
- return [
- { name: "position", value: "absolute" },
- { name: "left", value: `${item.frame.xPx}px` },
- { name: "top", value: `${item.frame.yPx}px` },
- { name: "width", value: `${item.frame.widthPx}px` },
- { name: "height", value: `${item.frame.heightPx}px` },
- { name: "box-sizing", value: "border-box" },
- { name: "display", value: "flex" },
- { name: "align-items", value: vertical === "top" ? "flex-start" : vertical === "bottom" ? "flex-end" : "center" },
- { name: "justify-content", value: "center" },
- ...(item.appearance.backgroundColor === undefined
- ? []
- : [{ name: "background-color", value: item.appearance.backgroundColor }]),
- ...(item.appearance.borderRadiusPx === undefined
- ? []
- : [{ name: "border-radius", value: `${item.appearance.borderRadiusPx}px` }]),
- ...(item.appearance.paddingPx === undefined
- ? []
- : [{ name: "padding", value: `${item.appearance.paddingPx}px` }]),
- ];
+export function sealTextMotion(value: TextMotion): TextMotion {
+ const result = canonicalize(value) as unknown as TextMotion;
+ assertTextMotion(result);
+ return result;
}
-function textStyle(appearance: TextAppearance): VisualStyleDeclaration[] {
- return [
- { name: "width", value: "100%" },
- { name: "white-space", value: "pre-wrap" },
- { name: "color", value: appearance.color },
- { name: "font-size", value: `${appearance.fontSizePx}px` },
- { name: "font-weight", value: appearance.fontWeight ?? 400 },
- { name: "line-height", value: appearance.lineHeight ?? 1.2 },
- { name: "text-align", value: appearance.align ?? "center" },
- ...(appearance.fontFamily === undefined ? [] : [{ name: "font-family", value: appearance.fontFamily }]),
- ...(appearance.letterSpacingPx === undefined ? [] : [{ name: "letter-spacing", value: `${appearance.letterSpacingPx}px` }]),
- ];
+export const stillTextMotion = (id = "still"): TextMotion => sealTextMotion({
+ contract: "svml.text-motion@1",
+ id,
+ sequences: [],
+});
+
+export function assertTextItemSpec(value: TextItemSpec): void {
+ if (value.contract !== "svml.text-item-spec@1") throw new Error("Unsupported TextItemSpec contract.");
+ nonEmpty(value.id, "TextItemSpec id");
+ assertDocument(value.document, `${value.id} document`);
}
-export function sealTextTrackSpec(value: TextTrackSpec): TextTrackSpec {
- return canonicalSpec(value);
+export function sealTextItemSpec(value: TextItemSpec): TextItemSpec {
+ const result = canonicalize(value) as unknown as TextItemSpec;
+ assertTextItemSpec(result);
+ return result;
}
-function canonicalSpec(value: TextTrackSpec): TextTrackSpec {
- return {
- contract: "svml.text-track-spec@1",
- id: value.id,
- items: value.items.map((item) => ({
- id: item.id,
- text: item.text,
- during: "full",
- z: item.z,
- frame: { ...item.frame },
- appearance: { ...item.appearance },
- })),
- };
+export function assertTextTrackHeader(value: TextTrackHeader): void {
+ if (value.contract !== "svml.text-track-header@1") throw new Error("Unsupported TextTrackHeader contract.");
+ nonEmpty(value.id, "TextTrackHeader id");
}
-export function assertTextTrackSpec(spec: TextTrackSpec): void {
- if (spec.contract !== "svml.text-track-spec@1" || !spec.id || spec.items.length === 0) {
- throw new Error("TextTrackSpec identity or items are invalid.");
- }
- const ids = new Set<string>();
- for (const item of spec.items) {
- if (!item.id || !item.text || item.during !== "full" || ids.has(item.id) || !Number.isSafeInteger(item.z)) {
- throw new Error("TextTrackSpec contains an invalid item.");
- }
- ids.add(item.id);
- assertSpatialFrame(item.frame);
- assertAppearance(item.appearance, `${item.id} appearance`);
- }
+export function sealTextTrackHeader(value: TextTrackHeader): TextTrackHeader {
+ const result = canonicalize(value) as unknown as TextTrackHeader;
+ assertTextTrackHeader(result);
+ return result;
}
-export function compileTextTrackProgram(programSpace: ProgramSpace, spec: TextTrackSpec): TextTrackProgram {
- assertProgramSpaceIdentity(programSpace);
- assertTextTrackSpec(spec);
- return sealTextTrackProgram({
- contract: "svml.text-track-program@1",
- id: spec.id,
- items: spec.items.map((item) => ({
- id: item.id,
- text: item.text,
- span: { startFrame: 0, endFrameExclusive: programSpaceFrameCount(programSpace) },
- z: item.z,
- tieBreak: `${spec.id}:${item.id}`,
- frame: item.frame,
- appearance: item.appearance,
- })),
- });
+function assertGeometry(geometry: TextGeometry): void {
+ if (geometry.kind === "point") assertSpatialPoint(geometry.point);
+ else if (geometry.kind === "area") assertSpatialFrame(geometry.frame);
+ else if (geometry.kind === "path") assertSpatialPath(geometry.path);
+ else throw new Error("Text geometry is unsupported.");
}
-export function renderTextTrack(programSpace: ProgramSpace, program: TextTrackProgram): VisualTrack {
- assertTextTrackProgramIdentity(program, programSpace);
- const track = sealVisualTrack({
- contract: "svml.visual-track@1",
- visualIr: "svml.visual-ir@1",
- id: program.id,
- presents: program.items.map((item) => ({
- id: item.id,
- span: { ...item.span },
- stacking: { order: item.z, tieBreak: item.tieBreak },
- elements: [
- { id: "root", kind: "box", order: 0, style: rootStyle(item) },
- { id: "text", parent: "root", kind: "text", order: 1, text: item.text, style: textStyle(item.appearance) },
- ],
- })),
- });
- assertVisualTrackIdentity(track, programSpace);
- return track;
+export function assertTextPlacement(value: TextPlacement): void {
+ if (value.contract !== "svml.text-placement@1") throw new Error("Unsupported TextPlacement contract.");
+ assertGeometry(value.geometry);
}
-export function sealTextTrackHeader(value: TextTrackHeader): TextTrackHeader {
- const result = canonicalize(value) as unknown as TextTrackHeader;
- assertTextTrackHeader(result);
+export function sealTextPlacement(value: TextPlacement): TextPlacement {
+ const result = canonicalize(value) as unknown as TextPlacement;
+ assertTextPlacement(result);
return result;
}
-export function assertTextTrackHeader(value: TextTrackHeader): void {
- if (
- value.contract !== "svml.text-track-header@1"
- || value.id.length === 0
- ) throw new Error("TextTrackHeader is invalid");
+export function bindPointTextPlacement(point: SpatialPoint): TextPlacement {
+ assertSpatialPoint(point);
+ return sealTextPlacement({ contract: "svml.text-placement@1", geometry: { kind: "point", point } });
}
-export function sealTextItemSpec(value: TextItemSpec): TextItemSpec {
- const result = canonicalize(value) as unknown as TextItemSpec;
- assertTextItemSpec(result);
- return result;
+export function bindAreaTextPlacement(frame: SpatialFrame): TextPlacement {
+ assertSpatialFrame(frame);
+ return sealTextPlacement({ contract: "svml.text-placement@1", geometry: { kind: "area", frame } });
}
-export function assertTextItemSpec(value: TextItemSpec): void {
- if (
- value.contract !== "svml.text-item-spec@1"
- || value.id.length === 0
- || value.text.length === 0
- || !Number.isSafeInteger(value.z)
- ) throw new Error("TextItemSpec is invalid");
- assertAppearance(value.appearance, `${value.id} appearance`);
+export function bindPathTextPlacement(path: SpatialPath): TextPlacement {
+ assertSpatialPath(path);
+ return sealTextPlacement({ contract: "svml.text-placement@1", geometry: { kind: "path", path } });
}
export function assertTextTrackSet(value: TextTrackSet): void {
- if (value.contract !== "svml.text-track-set@1") throw new Error("TextTrackSet is invalid");
+ if (value.contract !== "svml.text-track-set@1") throw new Error("Unsupported TextTrackSet contract.");
const ids = new Set<string>();
for (const item of value.items) {
- if (ids.has(item.id)) throw new Error(`TextTrackSet repeats Item ${item.id}`);
+ if (ids.has(item.id)) throw new Error(`TextTrackSet repeats ${item.id}.`);
ids.add(item.id);
+ assertGeometry(item.geometry);
+ assertDocument(item.document, `${item.id} document`);
+ assertTextStyle(item.style);
+ assertTextMotion(item.motion);
}
}
export function createTextTrackSet(): TextTrackSet {
+ return { contract: "svml.text-track-set@1", items: [] };
+}
+
+function occurrenceItem(
+ header: TextTrackHeader,
+ spec: TextItemSpec,
+ style: TextStyle,
+ motion: TextMotion,
+ geometry: TextGeometry,
+ occurrence: ProjectedOccurrence,
+ index: number,
+ count: number,
+): TextItem {
return {
- contract: "svml.text-track-set@1",
- items: [],
+ id: count === 1 ? spec.id : occurrence.id,
+ sourceOccurrenceId: occurrence.sourceOccurrenceId,
+ span: { ...occurrence.span },
+ geometry: structuredClone(geometry),
+ document: structuredClone(spec.document),
+ style: structuredClone(style),
+ motion: structuredClone(motion),
+ tieBreak: `${header.id}:${spec.id}:${index + 1}`,
};
}
-function appendItems(
+function append(
set: TextTrackSet,
+ header: TextTrackHeader,
spec: TextItemSpec,
- additions: readonly TextItem[],
+ style: TextStyle,
+ motion: TextMotion,
+ geometry: TextGeometry,
+ occurrences: readonly ProjectedOccurrence[],
): TextTrackSet {
assertTextTrackSet(set);
+ assertTextTrackHeader(header);
assertTextItemSpec(spec);
+ assertTextStyle(style);
+ assertTextMotion(motion);
+ assertGeometry(geometry);
const existing = new Set(set.items.map((item) => item.id));
- if (additions.some((item) => existing.has(item.id))) throw new Error(`Text Item ${spec.id} is duplicated`);
- return {
- contract: "svml.text-track-set@1",
- items: [...set.items, ...additions],
- };
+ const additions = occurrences.map((occurrence, index) => occurrenceItem(header, spec, style, motion, geometry, occurrence, index, occurrences.length));
+ if (additions.some((item) => existing.has(item.id))) throw new Error(`TextTrackSet already contains ${spec.id}.`);
+ return { contract: "svml.text-track-set@1", items: [...set.items, ...additions] };
}
-function itemFromSpec(
+export function appendProgramTextItem(
+ set: TextTrackSet,
+ header: TextTrackHeader,
+ space: ProgramSpace,
+ placement: TextPlacement,
spec: TextItemSpec,
- frame: SpatialFrame,
- id: string,
- span: TextItem["span"],
- tieBreak: string,
-): TextItem {
- assertSpatialFrame(frame);
- return {
- id,
- text: spec.text,
- span,
- z: spec.z,
- tieBreak,
- frame,
- appearance: spec.appearance,
- };
+ style: TextStyle,
+ motion: TextMotion,
+): TextTrackSet {
+ assertProgramSpaceIdentity(space);
+ assertTextPlacement(placement);
+ if (spec.expansion.kind !== "one") throw new Error("Program Text uses one occurrence.");
+ return append(set, header, spec, style, motion, placement.geometry, [projectProgramWindow({ itemId: spec.id, space, projection: spec.projection })]);
}
-export function appendFullTextItem(
+export function appendSelectionTextItem(
set: TextTrackSet,
header: TextTrackHeader,
+ map: CompleteSemanticMap,
+ selection: NarrativeSelectionRef,
space: ProgramSpace,
- frame: SpatialFrame,
+ placement: TextPlacement,
spec: TextItemSpec,
+ style: TextStyle,
+ motion: TextMotion,
): TextTrackSet {
- assertTextTrackSet(set);
- assertTextTrackHeader(header);
+ assertCompleteSemanticMapIdentity(map);
+ assertNarrativeSelectionIdentity(selection);
assertProgramSpaceIdentity(space);
- const projected = projectProgramWindow({
- itemId: spec.id,
- space,
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
- });
- return appendItems(set, spec, [itemFromSpec(
- spec,
- frame,
- spec.id,
- projected.span,
- `${header.id}:${spec.id}:1`,
- )]);
+ assertTextPlacement(placement);
+ return append(set, header, spec, style, motion, placement.geometry, assertWindowRelation(projectSelectionWindows({
+ itemId: spec.id, map, selection, space, projection: spec.projection, expansion: spec.expansion,
+ }), "disjoint"));
}
-export function appendSelectedTextItem(
+export function appendMomentTextItem(
set: TextTrackSet,
header: TextTrackHeader,
map: CompleteSemanticMap,
- selection: NarrativeSelectionRef,
+ moment: NarrativeMomentRef,
space: ProgramSpace,
- frame: SpatialFrame,
+ placement: TextPlacement,
spec: TextItemSpec,
+ style: TextStyle,
+ motion: TextMotion,
): TextTrackSet {
- assertTextTrackSet(set);
- assertTextTrackHeader(header);
assertCompleteSemanticMapIdentity(map);
- assertNarrativeSelectionIdentity(selection);
+ assertNarrativeMomentIdentity(moment);
assertProgramSpaceIdentity(space);
- const occurrences = assertWindowRelation(projectSelectionWindows({
- itemId: spec.id,
- map,
- selection,
- space,
- expansion: { kind: "each" },
- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
- }), "disjoint");
- return appendItems(set, spec, occurrences.map((occurrence, index) => itemFromSpec(
- spec,
- frame,
- occurrences.length === 1 ? spec.id : occurrence.id,
- occurrence.span,
- `${header.id}:${spec.id}:${index + 1}`,
- )));
+ assertTextPlacement(placement);
+ return append(set, header, spec, style, motion, placement.geometry, assertWindowRelation(projectMomentWindows({
+ itemId: spec.id, map, moment, space, projection: spec.projection, expansion: spec.expansion,
+ }), "disjoint"));
+}
+
+function programContent(value: TextTrackProgram): TextTrackProgram {
+ return {
+ contract: "svml.text-track-program@1",
+ id: value.id,
+ items: [...value.items].map((item) => structuredClone(item)).sort((left, right) =>
+ left.span.startFrame - right.span.startFrame
+ || left.style.stackingOrder - right.style.stackingOrder
+ || left.tieBreak.localeCompare(right.tieBreak)
+ || left.id.localeCompare(right.id)),
+ };
+}
+
+export function sealTextTrackProgram(value: TextTrackProgram): TextTrackProgram {
+ return programContent(value);
+}
+
+export function assertTextTrackProgramIdentity(program: TextTrackProgram, space: ProgramSpace): void {
+ assertProgramSpaceIdentity(space);
+ if (program.contract !== "svml.text-track-program@1") throw new Error("Unsupported TextTrackProgram contract.");
+ nonEmpty(program.id, "TextTrackProgram id");
+ if (program.items.length === 0) throw new Error("TextTrackProgram has no Items.");
+ const total = programSpaceFrameCount(space);
+ const ids = new Set<string>();
+ for (const item of program.items) {
+ nonEmpty(item.id, "Text Item id");
+ if (ids.has(item.id)) throw new Error(`TextTrackProgram repeats ${item.id}.`);
+ ids.add(item.id);
+ if (item.span.startFrame < 0 || item.span.endFrameExclusive <= item.span.startFrame || item.span.endFrameExclusive > total) {
+ throw new Error(`${item.id} is outside ProgramSpace.`);
+ }
+ assertGeometry(item.geometry);
+ assertDocument(item.document, `${item.id} document`);
+ assertTextStyle(item.style);
+ assertTextMotion(item.motion);
+ }
+}
+
+export function assertTextMaskSpec(spec: TextMaskSpec): void {
+ if (spec.contract !== "svml.text-mask-spec@1") throw new Error("Unsupported TextMaskSpec contract.");
+ nonEmpty(spec.id, "TextMaskSpec id");
+ if (!["alpha", "luminance"].includes(spec.mode)) throw new Error("TextMaskSpec mode is invalid.");
+ if (!["contain", "cover", "fill"].includes(spec.materialFit)) throw new Error("TextMaskSpec materialFit is invalid.");
+}
+
+export function sealTextMaskSpec(value: TextMaskSpec): TextMaskSpec {
+ const result = canonicalize(value) as unknown as TextMaskSpec;
+ assertTextMaskSpec(result);
+ return result;
}
export function finalizeTextTrack(header: TextTrackHeader, set: TextTrackSet): TextTrackProgram {
assertTextTrackHeader(header);
assertTextTrackSet(set);
- if (set.items.length === 0) throw new Error("TextTrack requires at least one Item");
- const program = sealTextTrackProgram({
- contract: "svml.text-track-program@1",
- id: header.id,
- items: set.items,
+ if (set.items.length === 0) throw new Error("TextTrack requires at least one Item.");
+ return sealTextTrackProgram({ contract: "svml.text-track-program@1", id: header.id, items: set.items });
+}
+
+function baseBoxStyle(geometry: TextGeometry): VisualStyleDeclaration[] {
+ if (geometry.kind === "area") return [
+ { name: "position", value: "absolute" },
+ { name: "left", value: `${geometry.frame.xPx}px` },
+ { name: "top", value: `${geometry.frame.yPx}px` },
+ { name: "width", value: `${geometry.frame.widthPx}px` },
+ { name: "height", value: `${geometry.frame.heightPx}px` },
+ ];
+ if (geometry.kind === "point") return [
+ { name: "position", value: "absolute" },
+ { name: "left", value: `${geometry.point.xPx}px` },
+ { name: "top", value: `${geometry.point.yPx}px` },
+ { name: "width", value: "max-content" },
+ { name: "height", value: "max-content" },
+ ];
+ return [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }];
+}
+
+function pointAnchorTransform(item: TextItem): string | undefined {
+ if (item.geometry.kind !== "point") return undefined;
+ const inline = item.style.point.anchorInline === "start" ? 0 : item.style.point.anchorInline === "center" ? -50 : -100;
+ const block = item.style.point.anchorBlock === "start" ? 0 : item.style.point.anchorBlock === "center" ? -50 : -100;
+ return `translate(${inline}%,${block}%)`;
+}
+
+function pathCommands(path: SpatialPath): VisualPathTextElement["path"] {
+ return path.commands.map((command) => {
+ if (command.kind === "move" || command.kind === "line") return { kind: command.kind, x: command.xPx, y: command.yPx };
+ if (command.kind === "quadratic") return { kind: command.kind, controlX: command.controlX, controlY: command.controlY, x: command.xPx, y: command.yPx };
+ if (command.kind === "cubic") return { kind: command.kind, control1X: command.control1X, control1Y: command.control1Y, control2X: command.control2X, control2Y: command.control2Y, x: command.xPx, y: command.yPx };
+ return { kind: "close" };
+ });
+}
+
+function pointFlow(item: TextItem): VisualTextFlowElement["flow"] {
+ const { maxLines: _maxLines, minimumScale: _minimumScale, ...area } = item.style.area;
+ return {
+ ...area,
+ form: { kind: "point", ...item.style.point },
+ inlineSize: "hug",
+ blockSize: "hug",
+ wrap: "none",
+ overflow: "visible",
+ clipToFrame: false,
+ columns: 1,
+ };
+}
+
+function terminalTextElement(item: TextItem, parent: string, order: number): VisualTextFlowElement | VisualPathTextElement {
+ if (item.geometry.kind === "path") return {
+ id: "text",
+ parent,
+ kind: "path-text",
+ order,
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ document: item.document,
+ typography: item.style.typography,
+ paints: item.style.paints,
+ path: pathCommands(item.geometry.path),
+ ...item.style.path,
+ sequences: item.motion.sequences,
+ ...(item.motion.pathMargin === undefined ? {} : { marginAnimation: item.motion.pathMargin }),
+ };
+ return {
+ id: "text",
+ parent,
+ kind: "text-flow",
+ order,
+ style: item.geometry.kind === "point"
+ ? [{ name: "position", value: "relative" }]
+ : [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ document: item.document,
+ typography: item.style.typography,
+ paints: item.style.paints,
+ flow: item.geometry.kind === "point"
+ ? pointFlow(item)
+ : { ...item.style.area, form: { kind: "area" } },
+ sequences: item.motion.sequences,
+ };
+}
+
+function maskText(item: TextItem): string {
+ if (item.geometry.kind !== "area") throw new Error(`${item.id} non-Area Text Mask must be materialized by an independent package.`);
+ if (item.motion.sequences.length !== 0) {
+ throw new Error(`${item.id} sequenced Text Mask must be materialized by an independent package.`);
+ }
+ if (item.document.paragraphs.length !== 1) {
+ throw new Error(`${item.id} multiline Text Mask must be materialized by an independent package.`);
+ }
+ return item.document.paragraphs.map((paragraph) => {
+ if (paragraph.style !== undefined) {
+ throw new Error(`${item.id} styled Text Mask paragraph must be materialized by an independent package.`);
+ }
+ return paragraph.inlines.map((inline) => {
+ if (inline.kind === "break") throw new Error(`${item.id} multiline Text Mask must be materialized by an independent package.`);
+ if (inline.style !== undefined || inline.language !== undefined || inline.direction !== undefined) {
+ throw new Error(`${item.id} rich Text Mask run must be materialized by an independent package.`);
+ }
+ return inline.text;
+ }).join("");
+ }).join("\n");
+}
+
+function maskTextElement(item: TextItem): VisualTextElement {
+ const typography = item.style.typography;
+ const area = item.style.area;
+ if (area.inlineSize !== "fixed" || area.blockSize !== "fixed" || area.wrap !== "none"
+ || area.columns !== 1 || area.overflow === "ellipsis" || area.overflow === "shrink"
+ || typography.writingMode !== "horizontal-tb" || typography.decorations.length !== 0) {
+ throw new Error(`${item.id} advanced Text Mask flow must be materialized by an independent package.`);
+ }
+ const fonts = typography.fonts;
+ if (fonts !== undefined) {
+ const primary = fonts[0];
+ if (primary === undefined || primary.weight !== typography.weight || primary.style !== typography.style || typography.synthesis !== "none") {
+ throw new Error(`${item.id} Text Mask typography must match its primary exact font without synthesis.`);
+ }
+ }
+ const style: VisualStyleDeclaration[] = [
+ { name: "position", value: "absolute" },
+ { name: "inset", value: 0 },
+ { name: "box-sizing", value: "border-box" },
+ { name: "align-items", value: area.blockAlign === "start" ? "flex-start" : area.blockAlign === "end" ? "flex-end" : "center" },
+ { name: "padding-top", value: `${area.paddingPx.blockStart}px` },
+ { name: "padding-right", value: `${area.paddingPx.inlineEnd}px` },
+ { name: "padding-bottom", value: `${area.paddingPx.blockEnd}px` },
+ { name: "padding-left", value: `${area.paddingPx.inlineStart}px` },
+ { name: "overflow", value: area.overflow === "clip" || area.clipToFrame ? "hidden" : "visible" },
+ { name: "text-align", value: area.inlineAlign },
+ { name: "font-size", value: `${typography.sizePx}px` },
+ ...(fonts === undefined ? [
+ { name: "font-weight", value: typography.weight } as const,
+ { name: "font-style", value: typography.style } as const,
+ { name: "font-synthesis", value: typography.synthesis } as const,
+ ] : []),
+ { name: "font-kerning", value: typography.kerning },
+ { name: "letter-spacing", value: `${typography.trackingPx}px` },
+ { name: "word-spacing", value: `${typography.wordSpacingPx}px` },
+ { name: "line-height", value: typography.lineHeight },
+ { name: "writing-mode", value: typography.writingMode },
+ { name: "text-transform", value: typography.transform },
+ { name: "font-variant-caps", value: typography.variantCaps },
+ { name: "tab-size", value: typography.tabSize },
+ { name: "text-indent", value: `${typography.indentationPx}px` },
+ { name: "vertical-align", value: typography.verticalAlign },
+ { name: "color", value: "#ffffff" },
+ ];
+ if (typography.direction !== "auto") style.push({ name: "direction", value: typography.direction });
+ if (typography.axes.length !== 0) {
+ style.push({ name: "font-variation-settings", value: typography.axes.map(({ tag, value }) => `"${tag}" ${value}`).join(",") });
+ }
+ if (typography.features.length !== 0) {
+ style.push({ name: "font-feature-settings", value: typography.features.map(({ tag, enabled }) => `"${tag}" ${enabled ? 1 : 0}`).join(",") });
+ }
+ return {
+ id: "text", parent: "mask", kind: "text", order: 1,
+ text: maskText(item), ...(fonts === undefined ? {} : { fonts }), style,
+ attributes: [
+ ...(typography.language === undefined ? [] : [{ name: "lang", value: typography.language }]),
+ ...(typography.direction === "auto" ? [] : [{ name: "dir", value: typography.direction }]),
+ ],
+ };
+}
+
+function assertMotionDomain(item: TextItem, durationFrames: number): void {
+ if (item.motion.item !== undefined && item.motion.item.keyframes.at(-1)?.atFrame !== durationFrames) {
+ throw new Error(`${item.id} item motion does not cover its complete window.`);
+ }
+ if (item.motion.item !== undefined && item.motion.item.keyframes[0]?.atFrame !== 0) {
+ throw new Error(`${item.id} item motion must start at frame zero.`);
+ }
+ if (item.motion.pathMargin !== undefined) {
+ if (item.geometry.kind !== "path") throw new Error(`${item.id} path-margin motion requires Path Text.`);
+ if (item.motion.pathMargin.keyframes[0]?.atFrame !== 0
+ || item.motion.pathMargin.keyframes.at(-1)?.atFrame !== durationFrames) {
+ throw new Error(`${item.id} path-margin motion must cover its complete window.`);
+ }
+ }
+}
+
+function elements(item: TextItem): VisualElement[] {
+ const durationFrames = item.span.endFrameExclusive - item.span.startFrame;
+ const rootStyle = baseBoxStyle(item.geometry);
+ const anchor = pointAnchorTransform(item);
+ if (anchor !== undefined) rootStyle.push({ name: "transform", value: anchor });
+ const root: VisualElement = { id: "placement", kind: "box", order: 0, style: rootStyle };
+ const motion: VisualElement = {
+ id: "motion",
+ parent: "placement",
+ kind: "box",
+ order: 1,
+ style: item.geometry.kind === "point"
+ ? [{ name: "position", value: "relative" }]
+ : [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+ ...(item.motion.item === undefined ? {} : { animation: item.motion.item }),
+ };
+ assertMotionDomain(item, durationFrames);
+ return [root, motion, terminalTextElement(item, "motion", 2)];
+}
+
+export function renderTextTrack(space: ProgramSpace, program: TextTrackProgram): VisualTrack {
+ assertTextTrackProgramIdentity(program, space);
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ visualIr: "svml.visual-ir@1",
+ id: program.id,
+ presents: program.items.map((item) => ({
+ id: item.id,
+ span: { ...item.span },
+ stacking: { order: item.style.stackingOrder, tieBreak: item.tieBreak },
+ elements: elements(item),
+ })),
+ });
+ assertVisualTrackIdentity(track, space);
+ return track;
+}
+
+export function renderTextMaskTrack(
+ space: ProgramSpace,
+ program: TextTrackProgram,
+ material: CompositableSurfaceRef,
+ spec: TextMaskSpec,
+): VisualTrack {
+ assertTextTrackProgramIdentity(program, space);
+ assertCompositableSurfaceRef(material);
+ assertTextMaskSpec(spec);
+ if (material.timing.kind !== "still") {
+ throw new Error("Official Text Mask requires one explicit still material Surface; timed materials use an independent package.");
+ }
+ const track = sealVisualTrack({
+ contract: "svml.visual-track@1",
+ visualIr: "svml.visual-ir@1",
+ id: spec.id,
+ presents: program.items.map((item) => {
+ const durationFrames = item.span.endFrameExclusive - item.span.startFrame;
+ assertMotionDomain(item, durationFrames);
+ const style = baseBoxStyle(item.geometry);
+ const anchor = pointAnchorTransform(item);
+ if (anchor !== undefined) style.push({ name: "transform", value: anchor });
+ return {
+ id: item.id,
+ span: { ...item.span },
+ stacking: { order: item.style.stackingOrder, tieBreak: `${item.tieBreak}:mask` },
+ elements: [
+ {
+ id: "mask", kind: "mask", order: 0, mode: spec.mode,
+ maskElement: "text", contentElement: "material", style,
+ ...(item.motion.item === undefined ? {} : { animation: item.motion.item }),
+ },
+ maskTextElement(item),
+ {
+ id: "material", parent: "mask", kind: "surface", order: 2, surface: material,
+ style: [
+ { name: "position", value: "absolute" }, { name: "inset", value: 0 },
+ { name: "width", value: "100%" }, { name: "height", value: "100%" },
+ { name: "object-fit", value: spec.materialFit },
+ ],
+ },
+ ],
+ };
+ }),
});
- return program;
+ assertVisualTrackIdentity(track, space);
+ return track;
}
diff --git a/packages/text-track/src/surface.ts b/packages/text-track/src/surface.ts
index e7d56efd..39630f35 100644
--- a/packages/text-track/src/surface.ts
+++ b/packages/text-track/src/surface.ts
@@ -1,217 +1,870 @@
import { narrativeTypes } from "@narratage/narrative";
-import type { NarrativeSelection } from "@narratage/narrative";
import { programSpaceTypes } from "@narratage/program-space";
import { semanticMapTypes } from "@narratage/semantic-map";
import { compositionTypes } from "@narratage/composition";
+import type {
+ VisualColorPaint,
+ VisualStyleDeclaration,
+ VisualTextDocument,
+ VisualTextPaintLayer,
+ VisualTextRunStyle,
+ VisualTextSequenceAnimation,
+ VisualTextTypography,
+} from "@narratage/composition";
+import {
+ assertFontArtifactRef,
+ assertFontStackRef,
+ mediaTypes,
+} from "@narratage/media";
+import type { FontArtifactRef, FontStackRef } from "@narratage/media";
import { spatialTypes } from "@narratage/spatial";
import { sealGraphFragment } from "@narratage/elaborator";
-import type { FragmentOperation } from "@narratage/elaborator";
+import type { AuthorValueRef, FragmentOperation, GraphFragment } from "@narratage/elaborator";
import { svsRecipeType } from "@narratage/svs";
import type { SvsRecipe } from "@narratage/svs";
-import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference, TextAttributeValue } from "@narratage/text";
+import type {
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceRecordDraft,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+import type {
+ OccurrenceExpansion,
+ TemporalDuration,
+ TemporalPointExpression,
+ TemporalWindowProjection,
+} from "@narratage/temporal";
import { textTrackProducers, textTrackTypes } from "./manifest.js";
-import { sealTextItemSpec, sealTextTrackHeader } from "./program.js";
-import type { TextItemSpec } from "./types.js";
+import {
+ sealTextItemSpec,
+ sealTextMaskSpec,
+ sealTextMotion,
+ sealTextStyle,
+ sealTextTrackHeader,
+ stillTextMotion,
+} from "./program.js";
+import type { TextItemSpec, TextMotion, TextStyle } from "./types.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-type SurfaceItem = {
- readonly suffix: string;
- readonly specName: string;
- readonly frameName: string;
- readonly selectionName?: string;
-};
-
-function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[]) {
- const selected = items.filter((item) => item.selectionName !== undefined);
- const operations: FragmentOperation[] = [{
- id: "text:set:empty",
- producer: textTrackProducers.createSet,
- inputs: {},
- result: { kind: "output", name: "set" },
- }];
- let current = "text:set:empty";
- items.forEach((item, index) => {
- const operationId = `text:set:append:${String(index + 1).padStart(4, "0")}`;
- operations.push(item.selectionName === undefined ? {
- id: operationId,
- producer: textTrackProducers.appendFull,
- inputs: {
- set: operation(current), header: input("header"), space: input("space"),
- frame: input(item.frameName), spec: input(item.specName),
- },
- result: { kind: "output", name: "set" },
- } : {
- id: operationId,
- producer: textTrackProducers.appendSelected,
- inputs: {
- set: operation(current),
- header: input("header"),
- map: input("map"),
- selection: input(item.selectionName),
- space: input("space"),
- frame: input(item.frameName),
- spec: input(item.specName),
- },
- result: { kind: "output", name: "set" },
- });
- current = operationId;
- });
- operations.push(
- { id: "text:finalize", producer: textTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },
- { id: "text:render", producer: textTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
- );
- const semanticInputs = ["space", "header", ...(selected.length === 0 ? [] : ["map"]),
- ...items.flatMap((item) => [item.frameName, item.specName,
- ...(item.selectionName === undefined ? [] : [item.selectionName])])];
- return sealGraphFragment({
- name: `@narratage/text-track/surface/${id}@1`,
- inputs: [
- { name: "space", type: programSpaceTypes.programSpace },
- { name: "header", type: textTrackTypes.header },
- ...(selected.length === 0 ? [] : [{ name: "map", type: semanticMapTypes.complete }]),
- ...items.flatMap((item) => [
- { name: item.frameName, type: spatialTypes.frame },
- { name: item.specName, type: textTrackTypes.itemSpec },
- ...(item.selectionName === undefined ? [] : [{ name: item.selectionName, type: narrativeTypes.selection }]),
- ]),
- ],
- operations,
- exports: [{
- name: "track", type: compositionTypes.visualTrack, root: operation("text:render"), semanticInputs, fidelity: "exact",
- }],
- });
+function localName(name: string): string {
+ return name.slice(name.lastIndexOf(":") + 1);
}
function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
}
-function exact(element: StructuredElement, names: readonly string[]): void {
- if (Object.keys(element.attributes).sort().join("\0") !== [...names].sort().join("\0")) throw new Error(`${element.name} requires exactly ${names.join(", ")}`);
+
+function allowed(element: StructuredElement, names: readonly string[], required: readonly string[] = []): void {
+ const unknown = Object.keys(element.attributes).filter((name) => !names.includes(name));
+ if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+ const missing = required.filter((name) => element.attributes[name] === undefined);
+ if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}.`);
}
-function text(element: StructuredElement, name: string): string {
+
+function empty(element: StructuredElement): void {
+ if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
+ throw new Error(`${element.name} must be empty.`);
+ }
+}
+
+function enumText<const T extends string>(
+ element: StructuredElement,
+ name: string,
+ values: readonly T[],
+ fallback?: T,
+): T {
+ const value = text(element, name, fallback);
+ if (!values.includes(value as T)) throw new Error(`${element.name}.${name} must be ${values.join(" or ")}.`);
+ return value as T;
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+ const value = element.attributes[name];
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
const value = element.attributes[name];
- if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be a non-empty string`);
+ if (value === undefined) return undefined;
+ if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
return value.trim();
}
-function ref(element: StructuredElement, name: string, expected: SurfaceResolvedReference["type"], resolve: (path: string) => SurfaceResolvedReference | undefined) {
- const raw: TextAttributeValue | undefined = element.attributes[name];
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference`);
- const value = resolve(raw.path);
- if (!value || !sameType(value.type, expected)) throw new Error(`${element.name}.${name} cannot resolve a value of the required type`);
+
+function numeric(element: StructuredElement, name: string, fallback?: number): number {
+ const raw = optionalText(element, name);
+ if (raw === undefined && fallback !== undefined) return fallback;
+ const value = Number(raw);
+ if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+ return value;
+}
+
+function integer(element: StructuredElement, name: string, fallback?: number): number {
+ const value = numeric(element, name, fallback);
+ if (!Number.isSafeInteger(value)) throw new Error(`${element.name}.${name} must be a safe integer.`);
return value;
}
-function recipe(value: SurfaceResolvedReference): SvsRecipe {
- if (!sameType(value.type, svsRecipeType) || value.record?.value.kind !== "inline") throw new Error("Text appearance must be an authored SVS Recipe");
- return value.record.value.value as unknown as SvsRecipe;
+
+function booleanValue(value: unknown, label: string, fallback: boolean): boolean {
+ if (value === undefined) return fallback;
+ if (value === true || value === "true") return true;
+ if (value === false || value === "false") return false;
+ throw new Error(`${label} must be true or false.`);
+}
+
+function reference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: SurfaceResolvedReference["type"],
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const result = resolve(raw.path);
+ if (result === undefined || !sameType(result.type, expected)) throw new Error(`${label} cannot resolve the required type.`);
+ return result;
+}
+
+function oneOfReference(
+ raw: TextAttributeValue | undefined,
+ label: string,
+ expected: readonly SurfaceResolvedReference["type"][],
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const result = resolve(raw.path);
+ if (result === undefined || !expected.some((type) => sameType(result.type, type))) {
+ throw new Error(`${label} cannot resolve one of the required types.`);
+ }
+ return result;
+}
+
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+ if (value.record?.value.kind !== "inline") throw new Error(`${label} must reference an authored inline Record.`);
+ return value.record.value.value as unknown as T;
+}
+
+function recipe(value: SurfaceResolvedReference, label: string): SvsRecipe {
+ if (!sameType(value.type, svsRecipeType)) throw new Error(`${label} must reference an SVS Recipe.`);
+ return inline<SvsRecipe>(value, label);
}
-function propNumber(value: SvsRecipe, name: string): number {
+
+function propNumber(value: SvsRecipe, name: string, fallback?: number): number {
const result = value.properties[name];
- if (typeof result !== "number" || !Number.isFinite(result)) throw new Error(`Text Recipe ${name} must be a number`);
+ if (result === undefined && fallback !== undefined) return fallback;
+ if (typeof result !== "number" || !Number.isFinite(result)) throw new Error(`Text Recipe ${name} must be a number.`);
return result;
}
-function propString(value: SvsRecipe, name: string): string {
+
+function propString(value: SvsRecipe, name: string, fallback?: string): string {
const result = value.properties[name];
- if (typeof result !== "string" || !result) throw new Error(`Text Recipe ${name} must be a string`);
+ if (result === undefined && fallback !== undefined) return fallback;
+ if (typeof result !== "string" || !result.trim()) throw new Error(`Text Recipe ${name} must be text.`);
+ return result.trim();
+}
+
+function propBoolean(value: SvsRecipe, name: string, fallback: boolean): boolean {
+ return booleanValue(value.properties[name], `Text Recipe ${name}`, fallback);
+}
+
+function exactFonts(
+ element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): FontArtifactRef[] {
+ const raw = element.attributes.font;
+ if (raw === undefined) throw new Error(`${element.name}.font must reference one exact FontArtifactRef or FontStackRef.`);
+ const resolved = oneOfReference(raw, `${element.name}.font`, [mediaTypes.fontArtifact, mediaTypes.fontStack], resolve);
+ if (sameType(resolved.type, mediaTypes.fontArtifact)) {
+ const font = inline<FontArtifactRef>(resolved, `${element.name}.font`);
+ assertFontArtifactRef(font, `${element.name}.font`);
+ return [font];
+ }
+ const stack = inline<FontStackRef>(resolved, `${element.name}.font`);
+ assertFontStackRef(stack, `${element.name}.font`);
+ return [...stack.faces];
+}
+
+function splitNumbers(value: string, label: string, count: 1 | 2 | 4): number[] {
+ const result = value.trim().split(/\s+/u).map(Number);
+ if (![1, 2, 4].includes(result.length) || result.some((item) => !Number.isFinite(item) || item < 0)) {
+ throw new Error(`${label} must contain one, two or four non-negative numbers.`);
+ }
+ if (count === 1) return [result[0]!];
+ if (count === 2) return result.length === 1 ? [result[0]!, result[0]!] : [result[0]!, result[1]!];
+ if (result.length === 1) return [result[0]!, result[0]!, result[0]!, result[0]!];
+ if (result.length === 2) return [result[0]!, result[1]!, result[0]!, result[1]!];
return result;
}
-export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- const trackAttributes = Object.keys(element.attributes).sort().join("\0");
- if (trackAttributes !== ["id", "space"].sort().join("\0")
- && trackAttributes !== ["id", "map", "space"].sort().join("\0")) {
- throw new Error(`${element.name} requires id and space; map is required when an Item uses a Selection`);
+function gradientStops(element: StructuredElement): Array<{ readonly offset: number; readonly color: string; readonly opacity: number }> {
+ const stops = element.children.flatMap((child) => {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Stop children.`);
+ return [];
+ }
+ if (localName(child.name) !== "Stop") throw new Error(`${element.name} accepts only Stop children.`);
+ allowed(child, ["offset", "color", "opacity"], ["offset", "color"]);
+ if (child.children.some((nested) => nested.kind === "element" || nested.value.trim())) throw new Error(`${child.name} must be empty.`);
+ return [{ offset: numeric(child, "offset"), color: text(child, "color"), opacity: numeric(child, "opacity", 1) }];
+ });
+ if (stops.length < 2) throw new Error(`${element.name} requires at least two Stops.`);
+ let previous = -1;
+ for (const [index, stop] of stops.entries()) {
+ if (stop.offset < 0 || stop.offset > 1 || stop.offset < previous || stop.opacity < 0 || stop.opacity > 1) {
+ throw new Error(`${element.name}.Stop.${index + 1} must have ordered offsets and normalized opacity.`);
+ }
+ previous = stop.offset;
+ }
+ return stops;
+}
+
+function gradient(element: StructuredElement): VisualColorPaint {
+ const name = localName(element.name);
+ if (name === "Linear") {
+ allowed(element, ["angle"], ["angle"]);
+ return { kind: "linear-gradient", angleDeg: numeric(element, "angle"), stops: gradientStops(element) };
+ }
+ if (name === "Radial") {
+ allowed(element, ["x", "y"], ["x", "y"]);
+ const center = { x: numeric(element, "x"), y: numeric(element, "y") };
+ if (center.x < 0 || center.x > 1 || center.y < 0 || center.y > 1) {
+ throw new Error(`${element.name} center must be normalized.`);
+ }
+ return { kind: "radial-gradient", center, stops: gradientStops(element) };
+ }
+ throw new Error(`${element.name} is not a gradient.`);
+}
+
+function paintFrom(element: StructuredElement, structuralChildren: readonly string[] = []): VisualColorPaint {
+ const color = optionalText(element, "color");
+ const gradients = element.children.filter((child): child is StructuredElement => child.kind === "element" && ["Linear", "Radial"].includes(localName(child.name)));
+ const unknown = element.children.filter((child): child is StructuredElement => child.kind === "element" && ![...structuralChildren, "Linear", "Radial"].includes(localName(child.name)));
+ if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]!.name}.`);
+ if (color !== undefined && gradients.length > 0) throw new Error(`${element.name} cannot combine color with a gradient.`);
+ if (gradients.length > 1) throw new Error(`${element.name} accepts one gradient.`);
+ if (color !== undefined) return { kind: "solid", color };
+ if (gradients[0] !== undefined) return gradient(gradients[0]);
+ throw new Error(`${element.name} requires color or one Linear/Radial child.`);
+}
+
+function parseBox(element: StructuredElement): VisualTextPaintLayer {
+ allowed(element, [
+ "target", "continuity", "color", "padding", "radius", "border-color", "border-width", "border-style",
+ ], ["target"]);
+ const target = text(element, "target") as Extract<VisualTextPaintLayer, { kind: "box" }>["target"];
+ if (!["frame", "content", "paragraph", "line", "run", "word", "grapheme"].includes(target)) throw new Error(`${element.name}.target is invalid.`);
+ const continuity = enumText(element, "continuity", ["isolated", "joined"] as const, "isolated");
+ if (continuity === "joined" && !["line", "word", "grapheme"].includes(target)) {
+ throw new Error(`${element.name}.continuity joined is invalid for ${target}.`);
+ }
+ const padding = splitNumbers(text(element, "padding", "0"), `${element.name}.padding`, 4);
+ const radius = splitNumbers(text(element, "radius", "0"), `${element.name}.radius`, 4);
+ const borderWidth = splitNumbers(text(element, "border-width", "0"), `${element.name}.border-width`, 4);
+ const shadows: Extract<VisualTextPaintLayer, { kind: "box" }>["decoration"]["shadows"][number][] = [];
+ let tail: Extract<VisualTextPaintLayer, { kind: "box" }>["decoration"]["tail"];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only gradient, BoxShadow and Tail children.`);
+ continue;
+ }
+ const name = localName(child.name);
+ if (name === "Linear" || name === "Radial") continue;
+ if (name === "BoxShadow") {
+ allowed(child, ["color", "x", "y", "blur", "spread"], ["color"]);
+ const blurPx = numeric(child, "blur", 0);
+ if (blurPx < 0) throw new Error(`${child.name}.blur must not be negative.`);
+ shadows.push({ paint: paintFrom(child), offsetX: numeric(child, "x", 0), offsetY: numeric(child, "y", 0), blurPx, spreadPx: numeric(child, "spread", 0) });
+ continue;
+ }
+ if (name === "Tail") {
+ if (tail !== undefined) throw new Error(`${element.name} accepts one Tail.`);
+ allowed(child, ["side", "offset", "width", "height", "color"], ["side", "offset", "width", "height", "color"]);
+ empty(child);
+ const widthPx = numeric(child, "width");
+ const heightPx = numeric(child, "height");
+ if (widthPx < 0 || heightPx < 0) throw new Error(`${child.name} dimensions must not be negative.`);
+ tail = { side: enumText(child, "side", ["top", "right", "bottom", "left"] as const), offset: numeric(child, "offset"), widthPx, heightPx, paint: paintFrom(child) };
+ continue;
+ }
+ }
+ const fill = element.attributes.color === undefined && !element.children.some((child) => child.kind === "element" && ["Linear", "Radial"].includes(localName(child.name)))
+ ? undefined : paintFrom(element, ["BoxShadow", "Tail"]);
+ const borderColor = optionalText(element, "border-color");
+ return {
+ kind: "box", target, continuity,
+ decoration: {
+ ...(fill === undefined ? {} : { fill }),
+ ...(borderColor === undefined || borderWidth.every((value) => value === 0) ? {} : {
+ border: {
+ paint: { kind: "solid", color: borderColor },
+ widthsPx: { top: borderWidth[0]!, right: borderWidth[1]!, bottom: borderWidth[2]!, left: borderWidth[3]! },
+ style: text(element, "border-style", "solid") as "solid" | "dashed" | "dotted",
+ },
+ }),
+ paddingPx: { top: padding[0]!, right: padding[1]!, bottom: padding[2]!, left: padding[3]! },
+ radiiPx: { topLeft: radius[0]!, topRight: radius[1]!, bottomRight: radius[2]!, bottomLeft: radius[3]! },
+ shadows,
+ ...(tail === undefined ? {} : { tail }),
+ },
+ };
+}
+
+function parsePaintLayer(element: StructuredElement): VisualTextPaintLayer {
+ const name = localName(element.name);
+ if (name === "Fill") {
+ allowed(element, ["color"]);
+ return { kind: "fill", paint: paintFrom(element) };
}
+ if (name === "Stroke") {
+ allowed(element, ["color", "width", "placement"], ["width", "placement"]);
+ const placement = enumText(element, "placement", ["inside", "center", "outside"] as const);
+ const widthPx = numeric(element, "width");
+ if (widthPx < 0) throw new Error(`${element.name}.width must not be negative.`);
+ return { kind: "stroke", paint: paintFrom(element), widthPx, placement };
+ }
+ if (name === "Shadow") {
+ allowed(element, ["color", "x", "y", "blur", "spread"], ["x", "y", "blur"]);
+ const blurPx = numeric(element, "blur");
+ if (blurPx < 0) throw new Error(`${element.name}.blur must not be negative.`);
+ return { kind: "shadow", paint: paintFrom(element), offsetX: numeric(element, "x"), offsetY: numeric(element, "y"), blurPx, spreadPx: numeric(element, "spread", 0) };
+ }
+ if (name === "Glow") {
+ allowed(element, ["color", "blur", "spread"], ["blur"]);
+ const blurPx = numeric(element, "blur");
+ const spreadPx = numeric(element, "spread", 0);
+ if (blurPx < 0 || spreadPx < 0) throw new Error(`${element.name} blur and spread must not be negative.`);
+ return { kind: "glow", paint: paintFrom(element), blurPx, spreadPx };
+ }
+ if (name === "Box") return parseBox(element);
+ throw new Error(`${element.name} is not a Text Paint layer.`);
+}
+
+const STYLE_PROPERTIES = new Set([
+ "stack-order", "size", "weight", "font-style", "line-height", "tracking", "word-spacing",
+ "kerning", "synthesis", "language", "direction", "writing-mode", "baseline-shift", "vertical-align", "tab-size", "indent",
+ "paragraph-before", "paragraph-after", "transform", "caps", "cjk-spacing", "punctuation-trim",
+ "fill", "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow",
+ "max-lines", "minimum-scale", "clip", "columns", "column-gap", "metric-edge",
+ "point-anchor-inline", "point-anchor-block", "path-side", "path-orientation", "path-start-margin",
+ "path-end-margin", "path-align", "path-reverse", "path-overflow",
+]);
+
+export const decodeTextStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "recipe", "font"], ["id", "recipe", "font"]);
const id = text(element, "id");
- const space = ref(element, "space", programSpaceTypes.programSpace, resolveReference);
- const header = sealTextTrackHeader({ contract: "svml.text-track-header@1", id });
- const headerId = `${id}.header`;
- const records: Array<{
- id: string;
- type: typeof textTrackTypes.header | typeof textTrackTypes.itemSpec;
- value: { kind: "inline"; value: ReturnType<typeof sealTextTrackHeader> | TextItemSpec };
- range: typeof element.range;
- }> = [{ id: headerId, type: textTrackTypes.header, value: { kind: "inline", value: header }, range: element.range }];
- let itemIndex = 0;
- const items = element.children.flatMap((child) => {
+ const value = recipe(reference(element.attributes.recipe, `${element.name}.recipe`, svsRecipeType, resolveReference), `${element.name}.recipe`);
+ const unknown = Object.keys(value.properties).filter((name) => !STYLE_PROPERTIES.has(name));
+ if (unknown.length > 0) throw new Error(`Text Recipe does not accept ${unknown[0]}.`);
+ const fonts = exactFonts(element, resolveReference);
+ const padding = splitNumbers(propString(value, "padding", "0"), "Text Recipe padding", 4);
+ const overflow = propString(value, "overflow", "visible") as TextStyle["area"]["overflow"];
+ const paints: VisualTextPaintLayer[] = [];
+ const axes: VisualTextTypography["axes"][number][] = [];
+ const features: VisualTextTypography["features"][number][] = [];
+ const decorations: VisualTextTypography["decorations"][number][] = [];
+ if (value.properties.fill !== undefined) paints.push({ kind: "fill", paint: { kind: "solid", color: propString(value, "fill") } });
+ for (const child of element.children) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts only Item children`);
- return [];
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Paint children.`);
+ continue;
}
- if (!child.name.endsWith(":Item") && child.name !== "Item") throw new Error(`${element.name} accepts only Item children`);
- itemIndex += 1;
- exact(child, ["text", "during", "frame", "appearance"]);
- const rawDuring = child.attributes.during;
- const selection = typeof rawDuring === "string"
- ? (() => {
- if (rawDuring.trim() !== "full") throw new Error(`${child.name}.during must be full or a NarrativeSelection reference`);
- return undefined;
- })()
- : ref(child, "during", narrativeTypes.selection, resolveReference);
- const appearance = recipe(ref(child, "appearance", svsRecipeType, resolveReference));
- const frame = ref(child, "frame", spatialTypes.frame, resolveReference);
- const expected = ["align", "fill", "font", "size", "stack-order", "tracking", "weight"];
- if (Object.keys(appearance.properties).sort().join("\0") !== expected.sort().join("\0")) throw new Error(`Text Recipe requires exactly ${expected.join(", ")}`);
- const align = propString(appearance, "align");
- if (align !== "left" && align !== "center" && align !== "right") throw new Error("Text Recipe align is invalid");
- const textAlign = align as "left" | "center" | "right";
- const suffix = String(itemIndex).padStart(4, "0");
+ const name = localName(child.name);
+ if (name === "Axis") {
+ allowed(child, ["tag", "value"], ["tag", "value"]);
+ empty(child);
+ const tag = text(child, "tag");
+ if (!/^[\x20-\x7e]{4}$/u.test(tag) || axes.some((axis) => axis.tag === tag)) throw new Error(`${child.name}.tag must be one unique four-byte OpenType tag.`);
+ axes.push({ tag, value: numeric(child, "value") });
+ } else if (name === "Feature") {
+ allowed(child, ["tag", "enabled"], ["tag", "enabled"]);
+ empty(child);
+ const tag = text(child, "tag");
+ if (!/^[\x20-\x7e]{4}$/u.test(tag) || features.some((feature) => feature.tag === tag)) throw new Error(`${child.name}.tag must be one unique four-byte OpenType tag.`);
+ features.push({ tag, enabled: booleanValue(child.attributes.enabled, `${child.name}.enabled`, false) });
+ } else if (name === "Decoration") {
+ allowed(child, ["line", "color", "style", "thickness", "offset", "skip-ink"], ["line"]);
+ const line = enumText(child, "line", ["underline", "overline", "line-through"] as const);
+ if (decorations.some((decoration) => decoration.line === line)) throw new Error(`${child.name}.line ${line} is repeated.`);
+ const thicknessPx = child.attributes.thickness === undefined ? undefined : numeric(child, "thickness");
+ if (thicknessPx !== undefined && thicknessPx < 0) throw new Error(`${child.name}.thickness must not be negative.`);
+ decorations.push({
+ line,
+ paint: paintFrom(child),
+ style: enumText(child, "style", ["solid", "double", "dotted", "dashed", "wavy"] as const, "solid"),
+ ...(thicknessPx === undefined ? {} : { thicknessPx }),
+ ...(child.attributes.offset === undefined ? {} : { offsetPx: numeric(child, "offset") }),
+ skipInk: booleanValue(child.attributes["skip-ink"], `${child.name}.skip-ink`, true),
+ });
+ } else paints.push(parsePaintLayer(child));
+ }
+ if (!paints.some((paint) => paint.kind === "fill" || paint.kind === "stroke")) {
+ throw new Error(`${element.name} requires at least one visible glyph Fill or Stroke.`);
+ }
+ const style = sealTextStyle({
+ contract: "svml.text-style@1", id,
+ stackingOrder: propNumber(value, "stack-order"),
+ typography: {
+ fonts,
+ sizePx: propNumber(value, "size"), weight: propNumber(value, "weight", 400),
+ style: propString(value, "font-style", "normal") as "normal" | "italic" | "oblique",
+ axes, features, synthesis: propString(value, "synthesis", "none") as TextStyle["typography"]["synthesis"],
+ kerning: propString(value, "kerning", "auto") as TextStyle["typography"]["kerning"],
+ trackingPx: propNumber(value, "tracking", 0), wordSpacingPx: propNumber(value, "word-spacing", 0),
+ lineHeight: propNumber(value, "line-height", 1.2),
+ ...(value.properties.language === undefined ? {} : { language: propString(value, "language") }),
+ direction: propString(value, "direction", "auto") as TextStyle["typography"]["direction"],
+ writingMode: propString(value, "writing-mode", "horizontal-tb") as TextStyle["typography"]["writingMode"],
+ baselineShiftPx: propNumber(value, "baseline-shift", 0), tabSize: propNumber(value, "tab-size", 4),
+ indentationPx: propNumber(value, "indent", 0), paragraphBeforePx: propNumber(value, "paragraph-before", 0),
+ paragraphAfterPx: propNumber(value, "paragraph-after", 0),
+ transform: propString(value, "transform", "none") as TextStyle["typography"]["transform"],
+ variantCaps: propString(value, "caps", "normal") as TextStyle["typography"]["variantCaps"],
+ verticalAlign: propString(value, "vertical-align", "baseline") as TextStyle["typography"]["verticalAlign"],
+ decorations,
+ cjk: {
+ textSpacing: propString(value, "cjk-spacing", "normal") as "normal" | "none",
+ punctuationTrim: propString(value, "punctuation-trim", "none") as "none" | "start" | "end" | "adjacent" | "all",
+ },
+ },
+ paints,
+ area: {
+ inlineSize: propString(value, "inline-size", "fixed") as "hug" | "fixed",
+ blockSize: propString(value, "block-size", "fixed") as "hug" | "fixed",
+ paddingPx: { inlineStart: padding[3]!, inlineEnd: padding[1]!, blockStart: padding[0]!, blockEnd: padding[2]! },
+ inlineAlign: propString(value, "align", "center") as TextStyle["area"]["inlineAlign"],
+ blockAlign: propString(value, "block-align", "center") as TextStyle["area"]["blockAlign"],
+ wrap: propString(value, "wrap", "word") as TextStyle["area"]["wrap"],
+ overflow,
+ ...(value.properties["max-lines"] === undefined ? {} : { maxLines: propNumber(value, "max-lines") }),
+ ...(overflow !== "shrink" ? {} : { minimumScale: propNumber(value, "minimum-scale") }),
+ clipToFrame: propBoolean(value, "clip", false), columns: propNumber(value, "columns", 1),
+ columnGapPx: propNumber(value, "column-gap", 0),
+ metricEdge: propString(value, "metric-edge", "line-box") as TextStyle["area"]["metricEdge"],
+ },
+ point: {
+ anchorInline: propString(value, "point-anchor-inline", "center") as TextStyle["point"]["anchorInline"],
+ anchorBlock: propString(value, "point-anchor-block", "center") as TextStyle["point"]["anchorBlock"],
+ },
+ path: {
+ side: propString(value, "path-side", "left") as "left" | "right",
+ orientation: propString(value, "path-orientation", "follow") as "follow" | "upright",
+ startMarginPx: propNumber(value, "path-start-margin", 0), endMarginPx: propNumber(value, "path-end-margin", 0),
+ align: propString(value, "path-align", "start") as "start" | "center" | "end",
+ reverse: propBoolean(value, "path-reverse", false), overflow: propString(value, "path-overflow", "visible") as "visible" | "clip",
+ },
+ });
+ return { records: [{ id, type: textTrackTypes.style, value: { kind: "inline", value: style }, range: element.range }], components: [], fragments: [] };
+};
+
+function keyframeStyle(element: StructuredElement): VisualStyleDeclaration[] {
+ const result: VisualStyleDeclaration[] = [];
+ const x = numeric(element, "x", 0);
+ const y = numeric(element, "y", 0);
+ const scale = numeric(element, "scale", 1);
+ const rotate = numeric(element, "rotate", 0);
+ const skewX = numeric(element, "skew-x", 0);
+ const skewY = numeric(element, "skew-y", 0);
+ if (["x", "y", "scale", "rotate", "skew-x", "skew-y"].some((name) => element.attributes[name] !== undefined)) {
+ result.push({ name: "transform", value: `translate(${x}px,${y}px) scale(${scale}) rotate(${rotate}deg) skew(${skewX}deg,${skewY}deg)` });
+ }
+ if (element.attributes.opacity !== undefined) result.push({ name: "opacity", value: numeric(element, "opacity") });
+ if (element.attributes.blur !== undefined) result.push({ name: "filter", value: `blur(${numeric(element, "blur")}px)` });
+ if (element.attributes.color !== undefined) result.push({ name: "color", value: text(element, "color") });
+ if (["clip-top", "clip-right", "clip-bottom", "clip-left"].some((name) => element.attributes[name] !== undefined)) {
+ result.push({ name: "clip-path", value: `inset(${numeric(element, "clip-top", 0)}% ${numeric(element, "clip-right", 0)}% ${numeric(element, "clip-bottom", 0)}% ${numeric(element, "clip-left", 0)}%)` });
+ }
+ if (result.length === 0) throw new Error(`${element.name} must animate at least one property.`);
+ return result;
+}
+
+const KEYFRAME_ATTRIBUTES = ["at", "easing", "x", "y", "scale", "rotate", "skew-x", "skew-y", "opacity", "blur", "color", "clip-top", "clip-right", "clip-bottom", "clip-left"] as const;
+
+export const decodeTextMotionSurface: StructuredSurfaceHandler = ({ element }) => {
+ allowed(element, ["id"], ["id"]);
+ const id = text(element, "id");
+ const itemKeyframes: NonNullable<TextMotion["item"]>["keyframes"][number][] = [];
+ const pathKeyframes: NonNullable<TextMotion["pathMargin"]>["keyframes"][number][] = [];
+ const sequences: VisualTextSequenceAnimation[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts ItemKeyframe, PathKeyframe and Sequence children.`);
+ continue;
+ }
+ const name = localName(child.name);
+ if (name === "ItemKeyframe") {
+ allowed(child, KEYFRAME_ATTRIBUTES, ["at"]);
+ if (child.children.some((nested) => nested.kind === "element" || nested.value.trim())) throw new Error(`${child.name} must be empty.`);
+ itemKeyframes.push({ atFrame: integer(child, "at"), ...(child.attributes.easing === undefined ? {} : { easing: text(child, "easing") as "linear" | "ease-in" | "ease-out" | "ease-in-out" }), style: keyframeStyle(child) });
+ continue;
+ }
+ if (name === "PathKeyframe") {
+ allowed(child, ["at", "margin", "easing"], ["at", "margin"]);
+ pathKeyframes.push({ atFrame: integer(child, "at"), startMarginPx: numeric(child, "margin"), ...(child.attributes.easing === undefined ? {} : { easing: text(child, "easing") as "linear" | "ease-in" | "ease-out" | "ease-in-out" }) });
+ continue;
+ }
+ if (name !== "Sequence") throw new Error(`${element.name} does not accept ${child.name}.`);
+ allowed(child, ["id", "unit", "start-index", "end-index", "order", "start-frame", "duration-frames", "stagger-frames", "cycles", "seed"], ["id", "unit", "start-index", "end-index", "duration-frames"]);
+ const keyframes = child.children.flatMap((nested) => {
+ if (nested.kind === "text") {
+ if (nested.value.trim()) throw new Error(`${child.name} accepts only Keyframe children.`);
+ return [];
+ }
+ if (localName(nested.name) !== "Keyframe") throw new Error(`${child.name} accepts only Keyframe children.`);
+ allowed(nested, KEYFRAME_ATTRIBUTES, ["at"]);
+ return [{ atProgress: numeric(nested, "at"), ...(nested.attributes.easing === undefined ? {} : { easing: text(nested, "easing") as "linear" | "ease-in" | "ease-out" | "ease-in-out" }), style: keyframeStyle(nested) }];
+ });
+ sequences.push({
+ id: text(child, "id"), unit: text(child, "unit") as VisualTextSequenceAnimation["unit"],
+ range: { start: integer(child, "start-index"), endExclusive: integer(child, "end-index") },
+ order: text(child, "order", "forward") as VisualTextSequenceAnimation["order"],
+ startFrame: integer(child, "start-frame", 0), unitDurationFrames: integer(child, "duration-frames"),
+ staggerFrames: integer(child, "stagger-frames", 0), cycles: integer(child, "cycles", 1),
+ ...(child.attributes.seed === undefined ? {} : { seed: integer(child, "seed") }), keyframes,
+ });
+ }
+ const motion = sealTextMotion({
+ contract: "svml.text-motion@1", id,
+ ...(itemKeyframes.length === 0 ? {} : { item: { keyframes: itemKeyframes } }),
+ sequences,
+ ...(pathKeyframes.length === 0 ? {} : { pathMargin: { keyframes: pathKeyframes } }),
+ });
+ return { records: [{ id, type: textTrackTypes.motion, value: { kind: "inline", value: motion }, range: element.range }], components: [], fragments: [] };
+};
+
+function divisor(left: number, right: number): number {
+ let a = Math.abs(left); let b = Math.abs(right);
+ while (b !== 0) [a, b] = [b, a % b];
+ return a;
+}
+
+function duration(value: string, label: string): TemporalDuration {
+ const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());
+ if (match === null) throw new Error(`${label} must be an exact duration such as 12f, 250ms or 1.5s.`);
+ const whole = Number(match[1]); const fraction = match[2] ?? ""; const unit = match[3];
+ if (!Number.isSafeInteger(whole)) throw new Error(`${label} is outside safe arithmetic.`);
+ if (unit === "f" || unit === "ms") {
+ if (fraction.length > 0) throw new Error(`${label} ${unit} duration must be an integer.`);
+ return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };
+ }
+ const scale = 10 ** fraction.length;
+ const numerator = whole * scale + (fraction.length === 0 ? 0 : Number(fraction));
+ const gcd = divisor(numerator, scale);
+ return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };
+}
+
+function negate(value: TemporalDuration): TemporalDuration {
+ return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value };
+}
+
+function pointExpression(value: string, label: string): TemporalPointExpression {
+ const trimmed = value.trim();
+ const refs = ["program.start", "program.end", "selection.start", "selection.end", "moment.cue"] as const;
+ for (const ref of refs) {
+ if (trimmed === ref) return { ref };
+ const match = new RegExp(`^${ref.replace(".", "\\.")}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);
+ if (match !== null) {
+ const offset = duration(match[2]!, `${label} offset`);
+ return { ref, offset: match[1] === "-" ? negate(offset) : offset };
+ }
+ }
+ return { ref: "absolute", at: duration(trimmed, label) };
+}
+
+type TemporalBinding = {
+ readonly kind: "program" | "selection" | "moment";
+ readonly projection: TemporalWindowProjection;
+ readonly source?: SurfaceResolvedReference;
+};
+
+function temporalBinding(element: StructuredElement, resolve: (path: string) => SurfaceResolvedReference | undefined): TemporalBinding {
+ const during = element.attributes.during;
+ const at = element.attributes.at;
+ const start = optionalText(element, "start");
+ const end = optionalText(element, "end");
+ const selection = element.attributes.selection;
+ const moment = element.attributes.moment;
+ const forms = Number(during !== undefined) + Number(at !== undefined) + Number(start !== undefined || end !== undefined);
+ if (forms !== 1) throw new Error(`${element.name} requires exactly one of during, at/for, or start/end.`);
+ if (during !== undefined) {
+ if (typeof during === "string") {
+ if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);
+ return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };
+ }
+ return { kind: "selection", source: reference(during, `${element.name}.during`, narrativeTypes.selection, resolve), projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } } };
+ }
+ if (at !== undefined) {
+ return { kind: "moment", source: reference(at, `${element.name}.at`, narrativeTypes.moment, resolve), projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: duration(text(element, "for"), `${element.name}.for`) } } };
+ }
+ if (start === undefined || end === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);
+ if (selection !== undefined && moment !== undefined) throw new Error(`${element.name} cannot bind Selection and Moment together.`);
+ if (selection !== undefined) return { kind: "selection", source: reference(selection, `${element.name}.selection`, narrativeTypes.selection, resolve), projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };
+ if (moment !== undefined) return { kind: "moment", source: reference(moment, `${element.name}.moment`, narrativeTypes.moment, resolve), projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };
+ return { kind: "program", projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };
+}
+
+function dedent(value: string): string {
+ const lines = value.replace(/^\n/u, "").replace(/\n\s*$/u, "").split("\n");
+ const indentation = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, /^\s*/u.exec(line)?.[0].length ?? 0), Number.POSITIVE_INFINITY);
+ return lines.map((line) => line.slice(Number.isFinite(indentation) ? indentation : 0)).join("\n");
+}
+
+function runStyle(value: SurfaceResolvedReference): VisualTextRunStyle {
+ const style = inline<TextStyle>(value, "Text inline Style");
+ return { typography: style.typography, paints: style.paints };
+}
+
+function paragraph(element: StructuredElement, index: number, resolve: (path: string) => SurfaceResolvedReference | undefined): VisualTextDocument["paragraphs"][number] {
+ allowed(element, ["id", "style"]);
+ const inlines: VisualTextDocument["paragraphs"][number]["inlines"][number][] = [];
+ let inlineIndex = 0;
+ for (const child of element.children) {
+ inlineIndex += 1;
+ if (child.kind === "text") {
+ if (child.value.length > 0) inlines.push({ kind: "text", id: `run-${inlineIndex}`, text: child.value });
+ continue;
+ }
+ const name = localName(child.name);
+ if (name === "Break") {
+ allowed(child, []);
+ inlines.push({ kind: "break", id: `break-${inlineIndex}` });
+ continue;
+ }
+ if (name !== "Span") throw new Error(`${element.name} accepts text, Span and Break children.`);
+ allowed(child, ["id", "style", "language", "direction"]);
+ if (child.children.some((nested) => nested.kind === "element")) throw new Error(`${child.name} cannot contain nested elements.`);
+ const spanText = child.children.map((nested) => nested.kind === "text" ? nested.value : "").join("");
+ if (spanText.length === 0) throw new Error(`${child.name} cannot be empty.`);
+ const styleRef = child.attributes.style === undefined ? undefined : reference(child.attributes.style, `${child.name}.style`, textTrackTypes.style, resolve);
+ inlines.push({
+ kind: "text", id: optionalText(child, "id") ?? `run-${inlineIndex}`, text: spanText,
+ ...(styleRef === undefined ? {} : { style: runStyle(styleRef) }),
+ ...(child.attributes.language === undefined ? {} : { language: text(child, "language") }),
+ ...(child.attributes.direction === undefined ? {} : { direction: text(child, "direction") as "auto" | "ltr" | "rtl" }),
+ });
+ }
+ if (inlines.length === 0) throw new Error(`${element.name} cannot be empty.`);
+ const styleRef = element.attributes.style === undefined ? undefined : reference(element.attributes.style, `${element.name}.style`, textTrackTypes.style, resolve);
+ return { id: optionalText(element, "id") ?? `paragraph-${index}`, inlines, ...(styleRef === undefined ? {} : { style: runStyle(styleRef) }) };
+}
+
+function document(element: StructuredElement, resolve: (path: string) => SurfaceResolvedReference | undefined): VisualTextDocument {
+ const paragraphChildren = element.children.filter((child): child is StructuredElement => child.kind === "element" && localName(child.name) === "P");
+ if (paragraphChildren.length > 0) {
+ const invalid = element.children.find((child) => child.kind === "element" ? localName(child.name) !== "P" : child.value.trim().length > 0);
+ if (invalid !== undefined) throw new Error(`${element.name} cannot mix P children with direct text.`);
+ return { paragraphs: paragraphChildren.map((child, index) => paragraph(child, index + 1, resolve)) };
+ }
+ if (element.children.some((child) => child.kind === "element")) throw new Error(`${element.name} direct content accepts no nested elements; use P and Span.`);
+ const content = dedent(element.children.map((child) => child.kind === "text" ? child.value : "").join(""));
+ if (!content.trim()) throw new Error(`${element.name} requires text content.`);
+ return { paragraphs: [{ id: "paragraph-1", inlines: [{ kind: "text", id: "run-1", text: content }] }] };
+}
+
+type FragmentItem = {
+ readonly suffix: string;
+ readonly binding: TemporalBinding["kind"];
+ readonly sourceName?: string;
+ readonly placementKind: "point" | "area" | "path";
+ readonly geometryName: string;
+ readonly specName: string;
+ readonly styleName: string;
+ readonly motionName: string;
+};
+
+function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphFragment {
+ const usesMap = items.some((item) => item.binding !== "program");
+ const operations: FragmentOperation[] = [{ id: "text:set:empty", producer: textTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } }];
+ let current = "text:set:empty";
+ for (const [index, item] of items.entries()) {
+ const bind = `text:placement:${String(index + 1).padStart(4, "0")}`;
+ operations.push({
+ id: bind,
+ producer: item.placementKind === "point" ? textTrackProducers.bindPoint : item.placementKind === "area" ? textTrackProducers.bindArea : textTrackProducers.bindPath,
+ inputs: { [item.placementKind === "point" ? "point" : item.placementKind === "area" ? "frame" : "path"]: input(item.geometryName) },
+ result: { kind: "output", name: "placement" },
+ });
+ const append = `text:set:append:${String(index + 1).padStart(4, "0")}`;
+ const common = {
+ set: operation(current), header: input("header"), space: input("space"), placement: operation(bind),
+ spec: input(item.specName), style: input(item.styleName), motion: input(item.motionName),
+ };
+ operations.push(item.binding === "program" ? {
+ id: append, producer: textTrackProducers.appendProgram, inputs: common, result: { kind: "output", name: "set" },
+ } : item.binding === "selection" ? {
+ id: append, producer: textTrackProducers.appendSelection, inputs: { ...common, map: input("map"), selection: input(item.sourceName!) }, result: { kind: "output", name: "set" },
+ } : {
+ id: append, producer: textTrackProducers.appendMoment, inputs: { ...common, map: input("map"), moment: input(item.sourceName!) }, result: { kind: "output", name: "set" },
+ });
+ current = append;
+ }
+ operations.push(
+ { id: "text:finalize", producer: textTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },
+ { id: "text:render", producer: textTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
+ );
+ const inputEntries = [
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "header", type: textTrackTypes.header },
+ ...(usesMap ? [{ name: "map", type: semanticMapTypes.complete }] : []),
+ ...items.flatMap((item) => [
+ { name: item.geometryName, type: item.placementKind === "point" ? spatialTypes.point : item.placementKind === "area" ? spatialTypes.frame : spatialTypes.path },
+ { name: item.specName, type: textTrackTypes.itemSpec },
+ { name: item.styleName, type: textTrackTypes.style },
+ { name: item.motionName, type: textTrackTypes.motion },
+ ...(item.sourceName === undefined ? [] : [{ name: item.sourceName, type: item.binding === "selection" ? narrativeTypes.selection : narrativeTypes.moment }]),
+ ]),
+ ];
+ const inputs = [...new Map(inputEntries.map((value) => [value.name, value])).values()];
+ return sealGraphFragment({
+ name: `@narratage/text-track/surface/${id}@1`, inputs, operations,
+ exports: [
+ {
+ name: "program", type: textTrackTypes.program, root: operation("text:finalize"),
+ semanticInputs: inputs.map((value) => value.name), fidelity: "exact",
+ },
+ {
+ name: "track", type: compositionTypes.visualTrack, root: operation("text:render"),
+ semanticInputs: inputs.map((value) => value.name), fidelity: "exact",
+ },
+ ],
+ });
+}
+
+export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "space", "map"], ["id", "space"]);
+ const id = text(element, "id");
+ const space = reference(element.attributes.space, `${element.name}.space`, programSpaceTypes.programSpace, resolveReference);
+ const headerId = `${id}.__header`;
+ const records: SurfaceRecordDraft[] = [{
+ id: headerId, type: textTrackTypes.header,
+ value: { kind: "inline", value: sealTextTrackHeader({ contract: "svml.text-track-header@1", id }) }, range: element.range,
+ }];
+ const defaultMotionId = `${id}.__still-motion`;
+ records.push({ id: defaultMotionId, type: textTrackTypes.motion, value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range });
+ const items: Array<FragmentItem & {
+ readonly geometry: SurfaceResolvedReference;
+ readonly style: SurfaceResolvedReference;
+ readonly motion: AuthorValueRef;
+ readonly source?: SurfaceResolvedReference;
+ readonly specId: string;
+ }> = [];
+ const sharedInputNames = new Map<string, string>();
+ const sharedInputName = (prefix: string, ref: AuthorValueRef, suffix: string): string => {
+ const key = `${prefix}:${JSON.stringify(ref)}`;
+ const existing = sharedInputNames.get(key);
+ if (existing !== undefined) return existing;
+ const name = `item-${suffix}-${prefix}`;
+ sharedInputNames.set(key, name);
+ return name;
+ };
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts Point, Area and Path children.`);
+ continue;
+ }
+ const form = localName(child.name);
+ if (form !== "Point" && form !== "Area" && form !== "Path") throw new Error(`${element.name} accepts Point, Area and Path children.`);
+ const index = items.length + 1;
+ const suffix = String(index).padStart(4, "0");
+ allowed(child, [
+ "id", "placement", "style", "motion", "during", "at", "for", "start", "end", "selection", "moment", "occurrences",
+ ], ["id", "placement", "style"]);
+ const itemId = text(child, "id");
+ const binding = temporalBinding(child, resolveReference);
+ const occurrences = text(child, "occurrences", "one");
+ if (occurrences !== "one" && occurrences !== "each") throw new Error(`${child.name}.occurrences must be one or each.`);
+ const expansion: OccurrenceExpansion = { kind: occurrences };
+ const placementKind = form.toLowerCase() as "point" | "area" | "path";
+ const geometry = reference(child.attributes.placement, `${child.name}.placement`, placementKind === "point" ? spatialTypes.point : placementKind === "area" ? spatialTypes.frame : spatialTypes.path, resolveReference);
+ const style = reference(child.attributes.style, `${child.name}.style`, textTrackTypes.style, resolveReference);
+ const motionRef = child.attributes.motion === undefined
+ ? ({ kind: "record", id: defaultMotionId } as const)
+ : reference(child.attributes.motion, `${child.name}.motion`, textTrackTypes.motion, resolveReference).ref;
const specId = `${id}.item.${suffix}.spec`;
const spec = sealTextItemSpec({
- contract: "svml.text-item-spec@1",
- id: `item-${suffix}`,
- text: text(child, "text"),
- z: propNumber(appearance, "stack-order"),
- appearance: {
- color: propString(appearance, "fill"), fontSizePx: propNumber(appearance, "size"),
- fontFamily: propString(appearance, "font"), fontWeight: propNumber(appearance, "weight"),
- letterSpacingPx: propNumber(appearance, "tracking"), align: textAlign,
- },
+ contract: "svml.text-item-spec@1", id: itemId,
+ document: document(child, resolveReference), projection: binding.projection, expansion,
});
records.push({ id: specId, type: textTrackTypes.itemSpec, value: { kind: "inline", value: spec }, range: child.range });
- return [{
- suffix,
- specId,
- specName: `item-${suffix}-spec`,
- frame,
- frameName: `item-${suffix}-frame`,
- ...(selection === undefined ? {} : { selection, selectionName: `item-${suffix}-selection` }),
- }];
- });
- if (items.length === 0) throw new Error(`${element.name} requires at least one Item`);
- const selected = items.filter((item) => item.selection !== undefined);
- const map = selected.length === 0
- ? undefined
- : ref(element, "map", semanticMapTypes.complete, resolveReference);
- if (selected.length === 0 && element.attributes.map !== undefined) {
- throw new Error(`${element.name}.map is unused because every Item uses during="full"`);
- }
- const fragmentItems: SurfaceItem[] = items.map((item) => ({
- suffix: item.suffix,
- specName: item.specName,
- frameName: item.frameName,
- ...(item.selectionName === undefined ? {} : { selectionName: item.selectionName }),
+ items.push({
+ suffix, binding: binding.kind, placementKind,
+ geometryName: sharedInputName("geometry", geometry.ref, suffix), specName: `item-${suffix}-spec`,
+ styleName: sharedInputName("style", style.ref, suffix), motionName: sharedInputName("motion", motionRef, suffix),
+ ...(binding.source === undefined ? {} : { sourceName: sharedInputName("source", binding.source.ref, suffix), source: binding.source }),
+ geometry, style, motion: motionRef, specId,
+ });
+ }
+ if (items.length === 0) throw new Error(`${element.name} requires at least one Point, Area or Path.`);
+ const usesMap = items.some((item) => item.binding !== "program");
+ const map = usesMap ? reference(element.attributes.map, `${element.name}.map`, semanticMapTypes.complete, resolveReference) : undefined;
+ if (!usesMap && element.attributes.map !== undefined) throw new Error(`${element.name}.map is unused.`);
+ const fragmentItems: FragmentItem[] = items.map(({ suffix, binding, sourceName, placementKind, geometryName, specName, styleName, motionName }) => ({
+ suffix, binding, placementKind, geometryName, specName, styleName, motionName, ...(sourceName === undefined ? {} : { sourceName }),
}));
- const fragment = createTextTrackSurfaceFragment(id, fragmentItems);
+ const fragment = createTrackFragment(id, fragmentItems);
return {
records,
components: [{
- id,
- fragment: fragment.id,
+ id, fragment: fragment.id,
inputs: {
- space: space.ref,
- header: { kind: "record", id: headerId },
- ...(map === undefined ? {} : { map: map.ref }),
+ space: space.ref, header: { kind: "record", id: headerId }, ...(map === undefined ? {} : { map: map.ref }),
...Object.fromEntries(items.flatMap((item) => [
- [item.frameName, item.frame.ref],
- [item.specName, { kind: "record" as const, id: item.specId }],
- ...(item.selection === undefined ? [] : [[item.selectionName!, item.selection.ref] as const]),
+ [item.geometryName, item.geometry.ref], [item.specName, { kind: "record" as const, id: item.specId }],
+ [item.styleName, item.style.ref], [item.motionName, item.motion],
+ ...(item.source === undefined ? [] : [[item.sourceName!, item.source.ref] as const]),
])),
},
- outputs: { track: `${id}.track` },
- range: element.range,
+ outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range,
+ }],
+ fragments: [fragment],
+ };
+};
+
+function createMaskFragment(id: string): GraphFragment {
+ const inputs = [
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "program", type: textTrackTypes.program },
+ { name: "material", type: mediaTypes.compositableSurface },
+ { name: "spec", type: textTrackTypes.maskSpec },
+ ];
+ return sealGraphFragment({
+ name: `@narratage/text-track/mask-surface/${id}@1`,
+ inputs,
+ operations: [{
+ id: "text-mask:render", producer: textTrackProducers.renderMask,
+ inputs: { space: input("space"), program: input("program"), material: input("material"), spec: input("spec") },
+ result: { kind: "output", name: "track" },
+ }],
+ exports: [{
+ name: "track", type: compositionTypes.visualTrack, root: operation("text-mask:render"),
+ semanticInputs: inputs.map((value) => value.name), fidelity: "exact",
+ }],
+ });
+}
+
+export const decodeTextMaskSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "space", "text", "material", "mode", "fit"], ["id", "space", "text", "material"]);
+ empty(element);
+ const id = text(element, "id");
+ const space = reference(element.attributes.space, `${element.name}.space`, programSpaceTypes.programSpace, resolveReference);
+ const program = reference(element.attributes.text, `${element.name}.text`, textTrackTypes.program, resolveReference);
+ const material = reference(element.attributes.material, `${element.name}.material`, mediaTypes.compositableSurface, resolveReference);
+ const specId = `${id}.__spec`;
+ const spec = sealTextMaskSpec({
+ contract: "svml.text-mask-spec@1", id,
+ mode: enumText(element, "mode", ["alpha", "luminance"] as const, "alpha"),
+ materialFit: enumText(element, "fit", ["contain", "cover", "fill"] as const, "cover"),
+ });
+ const fragment = createMaskFragment(id);
+ return {
+ records: [{ id: specId, type: textTrackTypes.maskSpec, value: { kind: "inline", value: spec }, range: element.range }],
+ components: [{
+ id, fragment: fragment.id,
+ inputs: { space: space.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
+ outputs: { track: `${id}.track` }, range: element.range,
}],
fragments: [fragment],
};
diff --git a/packages/text-track/src/types.ts b/packages/text-track/src/types.ts
index 4a9a93bd..c6af66cc 100644
--- a/packages/text-track/src/types.ts
+++ b/packages/text-track/src/types.ts
@@ -1,66 +1,111 @@
-import type { FrameSpan, Track } from "@narratage/composition";
-import type { SpatialFrame } from "@narratage/spatial";
+import type {
+ FrameSpan,
+ VisualAnimation,
+ VisualColorPaint,
+ VisualTextDocument,
+ VisualTextFlow,
+ VisualTextPaintLayer,
+ VisualTextSequenceAnimation,
+ VisualTextTypography,
+} from "@narratage/composition";
+import type { SpatialFrame, SpatialPath, SpatialPoint } from "@narratage/spatial";
+import type { OccurrenceExpansion, TemporalWindowProjection } from "@narratage/temporal";
-export type TextAppearance = {
- readonly color: string;
- readonly fontSizePx: number;
- readonly fontFamily?: string;
- readonly fontWeight?: number;
- readonly lineHeight?: number;
- readonly align?: "left" | "center" | "right";
- readonly verticalAlign?: "top" | "center" | "bottom";
- readonly backgroundColor?: string;
- readonly borderRadiusPx?: number;
- readonly paddingPx?: number;
- readonly letterSpacingPx?: number;
+export type TextDocument = VisualTextDocument;
+export type TextTypography = VisualTextTypography;
+export type TextPaint = VisualColorPaint;
+export type TextPaintLayer = VisualTextPaintLayer;
+
+export type TextAreaFlow = Omit<VisualTextFlow, "form">;
+
+export type TextStyle = {
+ readonly contract: "svml.text-style@1";
+ readonly id: string;
+ readonly stackingOrder: number;
+ readonly typography: TextTypography;
+ readonly paints: readonly TextPaintLayer[];
+ readonly area: TextAreaFlow;
+ readonly point: {
+ readonly anchorInline: "start" | "center" | "end";
+ readonly anchorBlock: "start" | "center" | "end";
+ };
+ readonly path: {
+ readonly side: "left" | "right";
+ readonly orientation: "follow" | "upright";
+ readonly startMarginPx: number;
+ readonly endMarginPx: number;
+ readonly align: "start" | "center" | "end";
+ readonly reverse: boolean;
+ readonly overflow: "visible" | "clip";
+ };
+};
+
+export type TextMotion = {
+ readonly contract: "svml.text-motion@1";
+ readonly id: string;
+ readonly item?: VisualAnimation;
+ readonly sequences: readonly VisualTextSequenceAnimation[];
+ readonly pathMargin?: {
+ readonly keyframes: readonly {
+ readonly atFrame: number;
+ readonly startMarginPx: number;
+ readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+ }[];
+ };
+};
+
+export type TextGeometry =
+ | { readonly kind: "point"; readonly point: SpatialPoint }
+ | { readonly kind: "area"; readonly frame: SpatialFrame }
+ | { readonly kind: "path"; readonly path: SpatialPath };
+
+export type TextPlacement = {
+ readonly contract: "svml.text-placement@1";
+ readonly geometry: TextGeometry;
+};
+
+export type TextItemSpec = {
+ readonly contract: "svml.text-item-spec@1";
+ readonly id: string;
+ readonly document: TextDocument;
+ readonly projection: TemporalWindowProjection;
+ readonly expansion: OccurrenceExpansion;
};
export type TextItem = {
readonly id: string;
- readonly text: string;
+ readonly sourceOccurrenceId: string;
readonly span: FrameSpan;
- readonly z: number;
+ readonly geometry: TextGeometry;
+ readonly document: TextDocument;
+ readonly style: TextStyle;
+ readonly motion: TextMotion;
readonly tieBreak: string;
- readonly frame: SpatialFrame;
- readonly appearance: TextAppearance;
};
-/** Package-owned authoring value. A future Text Surface or SVS recipe may produce it. */
export type TextTrackProgram = {
readonly contract: "svml.text-track-program@1";
readonly id: string;
readonly items: readonly TextItem[];
};
-export type TextTrackSpec = {
- readonly contract: "svml.text-track-spec@1";
+/**
+ * Separate graph contract for revealing one explicitly supplied owned Surface
+ * through an already authored Text Program. It is not a TextStyle mode and it
+ * never samples another Track or the final composite.
+ */
+export type TextMaskSpec = {
+ readonly contract: "svml.text-mask-spec@1";
readonly id: string;
- readonly items: readonly {
- readonly id: string;
- readonly text: string;
- readonly during: "full";
- readonly z: number;
- readonly frame: SpatialFrame;
- readonly appearance: TextAppearance;
- }[];
+ readonly mode: "alpha" | "luminance";
+ readonly materialFit: "contain" | "cover" | "fill";
};
-/** Stable Track identity used by the graph-first Surface fold. */
export type TextTrackHeader = {
readonly contract: "svml.text-track-header@1";
readonly id: string;
};
-/** Appearance and content are authored here; timing and placement remain explicit graph inputs. */
-export type TextItemSpec = {
- readonly contract: "svml.text-item-spec@1";
- readonly id: string;
- readonly text: string;
- readonly z: number;
- readonly appearance: TextAppearance;
-};
-
-/** Package-private immutable fold value for any number of full or selected Items. */
export type TextTrackSet = {
readonly contract: "svml.text-track-set@1";
readonly items: readonly TextItem[];
diff --git a/packages/text-track/test/text-track.test.ts b/packages/text-track/test/text-track.test.ts
index 1b998423..da1d5998 100644
--- a/packages/text-track/test/text-track.test.ts
+++ b/packages/text-track/test/text-track.test.ts
@@ -1,23 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { spatialComponent, videoContractManifests } from "../../test-support/video-domain.js";
+import { registerTypeValidatorFacets } from "@narratage/component-kit";
+import { compositionTypes, sealComposition, sealVisualTrack } from "@narratage/composition";
+import { computeModuleDigest, createResolvedClosure, sealBuildRequest, start } from "@narratage/core";
+import { AuthorFrontendRegistry, compileSourceClosure, resolveCompiledSourceExport } from "@narratage/elaborator";
import { compileHyperframesDocument } from "@narratage/hyperframes";
+import { mediaDependency, mediaTypes } from "@narratage/media";
+import type { CompositableSurfaceRef, FontArtifactRef } from "@narratage/media";
+import type { NarrativeSelectionRef } from "@narratage/narrative";
+import { sealProgramSpace } from "@narratage/program-space";
+import { programSpaceDependency, programSpaceTypes } from "@narratage/program-space";
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest } from "@narratage/protocol";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
import {
- appendSelectedTextItem,
+ appendSelectionTextItem,
+ bindAreaTextPlacement,
createTextTrackSet,
finalizeTextTrack,
assertTextTrackProgramIdentity,
renderTextTrack,
- sealTextTrackProgram,
+ renderTextMaskTrack,
sealTextItemSpec,
+ sealTextStyle,
sealTextTrackHeader,
+ sealTextTrackProgram,
+ stillTextMotion,
+ sealTextMotion,
+ sealTextMaskSpec,
+ decodeTextMotionSurface,
+ decodeTextMaskSurface,
+ decodeTextStyleSurface,
+ decodeTextTrackSurface,
+ textTrackManifest,
+ textTrackModuleRef,
+ textTrackProducers,
+ textTrackSurfaceImplementationDigests,
+ textTrackTypes,
} from "@narratage/text-track";
-import type { NarrativeSelectionRef } from "@narratage/narrative";
-import { sealProgramSpace } from "@narratage/program-space";
-import type { ProgramSpace } from "@narratage/program-space";
-import type { CompleteSemanticMap } from "@narratage/semantic-map";
-import { sealComposition, sealVisualTrack } from "@narratage/composition";
-import type { VisualTrack } from "@narratage/composition";
-import assert from "node:assert/strict";
-import test from "node:test";
-
+import type { TextStyle } from "@narratage/text-track";
+import { spatialDependency, spatialTypes } from "@narratage/spatial";
+import { svsManifest, svsRecipeType } from "@narratage/svs";
+import { TextSurfaceRegistry, createTextAuthorFrontend } from "@narratage/text";
+import { createRecordAdmitter, TypeValidatorRegistry } from "@narratage/validation";
const space = sealProgramSpace({
contract: "svml.program-space@1",
@@ -25,44 +52,140 @@ const space = sealProgramSpace({
frameRate: { numerator: 30, denominator: 1 },
});
-test("persistent and timed text are ordinary Presents in one VisualTrack", () => {
+const exactTestFont: FontArtifactRef = {
+ contract: "svml.font-artifact@1",
+ sources: [{ artifact: {
+ kind: "blob",
+ digest: digestOf("text-track-test-font"),
+ size: 1,
+ mediaType: "font/woff2",
+ } }],
+ weight: 700,
+ style: "normal",
+};
+
+const exactTestSurface: CompositableSurfaceRef = {
+ contract: "svml.compositable-surface@1",
+ artifact: {
+ kind: "blob",
+ digest: digestOf("text-track-test-surface"),
+ size: 1,
+ mediaType: "image/png",
+ },
+ width: 920,
+ height: 520,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: { kind: "still" },
+};
+
+function textStyle(id: string, stackingOrder = 50): TextStyle {
+ return sealTextStyle({
+ contract: "svml.text-style@1",
+ id,
+ stackingOrder,
+ typography: {
+ fonts: [exactTestFont],
+ sizePx: 48,
+ weight: 700,
+ style: "normal",
+ axes: [],
+ features: [],
+ synthesis: "none",
+ kerning: "auto",
+ trackingPx: 0,
+ wordSpacingPx: 0,
+ lineHeight: 1.2,
+ direction: "auto",
+ writingMode: "horizontal-tb",
+ baselineShiftPx: 0,
+ tabSize: 4,
+ indentationPx: 0,
+ paragraphBeforePx: 0,
+ paragraphAfterPx: 0,
+ transform: "none",
+ variantCaps: "normal",
+ verticalAlign: "baseline",
+ decorations: [],
+ cjk: { textSpacing: "normal", punctuationTrim: "none" },
+ },
+ paints: [
+ { kind: "fill", paint: { kind: "solid", color: "#ffffff" } },
+ {
+ kind: "box",
+ target: "content",
+ continuity: "isolated",
+ decoration: {
+ fill: { kind: "solid", color: "#111111" },
+ paddingPx: { top: 8, right: 12, bottom: 8, left: 12 },
+ radiiPx: { topLeft: 12, topRight: 12, bottomRight: 12, bottomLeft: 12 },
+ shadows: [],
+ },
+ },
+ ],
+ area: {
+ inlineSize: "fixed",
+ blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "center",
+ blockAlign: "center",
+ wrap: "word",
+ overflow: "visible",
+ clipToFrame: false,
+ columns: 1,
+ columnGapPx: 0,
+ metricEdge: "line-box",
+ },
+ point: { anchorInline: "center", anchorBlock: "center" },
+ path: {
+ side: "left",
+ orientation: "follow",
+ startMarginPx: 0,
+ endMarginPx: 0,
+ align: "start",
+ reverse: false,
+ overflow: "visible",
+ },
+ });
+}
+
+function document(text: string) {
+ return { paragraphs: [{ id: "paragraph", inlines: [{ kind: "text" as const, id: "run", text }] }] };
+}
+
+test("persistent and timed Text Items lower to ordinary VisualTrack Presents", () => {
+ const style = textStyle("editorial", 55);
const program = sealTextTrackProgram({
contract: "svml.text-track-program@1",
id: "editorial-text",
items: [
{
id: "watermark",
- text: "SVML",
+ sourceOccurrenceId: "program",
span: { startFrame: 0, endFrameExclusive: 150 },
- z: 90,
tieBreak: "watermark",
- frame: { contract: "svml.spatial-frame@1", xPx: 756, yPx: 76.8, widthPx: 270, heightPx: 153.6 },
- appearance: { color: "#ffffff", fontSizePx: 32, fontWeight: 700, align: "right" },
+ geometry: { kind: "point", point: { contract: "svml.spatial-point@1", xPx: 900, yPx: 80 } },
+ document: document("SVML"),
+ style: { ...style, id: "watermark", stackingOrder: 90 },
+ motion: stillTextMotion(),
},
{
id: "callout",
- text: "Intent, not timeline",
+ sourceOccurrenceId: "program",
span: { startFrame: 30, endFrameExclusive: 90 },
- z: 55,
tieBreak: "callout",
- frame: { contract: "svml.spatial-frame@1", xPx: 108, yPx: 1248, widthPx: 864, heightPx: 230.4 },
- appearance: {
- color: "#111111",
- fontSizePx: 48,
- fontFamily: "Inter, sans-serif",
- fontWeight: 800,
- backgroundColor: "#f8ff66",
- borderRadiusPx: 18,
- paddingPx: 16,
- },
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 108, yPx: 1248, widthPx: 864, heightPx: 230.4 } },
+ document: document("Intent, not timeline"),
+ style,
+ motion: stillTextMotion(),
},
],
});
+
assert.doesNotThrow(() => assertTextTrackProgramIdentity(program, space));
const track = renderTextTrack(space, program);
assert.deepEqual(track.presents.map((present) => present.id), ["watermark", "callout"]);
- assert.equal(track.presents[0]?.span.endFrameExclusive, 150);
- assert.equal(track.presents[1]?.span.endFrameExclusive, 90);
+ assert.equal(track.presents[0]?.elements[2]?.kind, "text-flow");
const lower = sealVisualTrack({
contract: "svml.visual-track@1",
@@ -75,80 +198,417 @@ test("persistent and timed text are ordinary Presents in one VisualTrack", () =>
elements: [{ id: "root", kind: "box", order: 0, style: [] }],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const rendered = compileHyperframesDocument(sealComposition({
contract: "svml.composition@1",
id: "text-film",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [track, lower],
}), space);
- assert.match(document.html, /Intent, not timeline/u);
- assert.match(document.html, /font-family:Inter, sans-serif/u);
- assert.ok(document.html.indexOf('data-svml-present-id="lower"') < document.html.indexOf('data-svml-present-id="callout"'));
+ assert.match(rendered.html, /data-svml-text-run="run"/u);
+ assert.match(rendered.html, /background-image:linear-gradient\(#111111,#111111\)/u);
+ assert.ok(rendered.html.indexOf('data-svml-present-id="lower"') < rendered.html.indexOf('data-svml-present-id="callout"'));
});
-test("TextTrackProgram rejects a frame span outside its ProgramSpace", () => {
+test("Text Mask explicitly consumes one authored Text Program and one owned still Surface", () => {
+ const program = sealTextTrackProgram({
+ contract: "svml.text-track-program@1", id: "mask-shape",
+ items: [{
+ id: "mask-title", sourceOccurrenceId: "program",
+ span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "mask-title",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 100, yPx: 200, widthPx: 800, heightPx: 240 } },
+ document: document("OWNED MASK"),
+ style: (() => {
+ const style = textStyle("mask-style", 75);
+ return { ...style, area: { ...style.area, wrap: "none" as const } };
+ })(),
+ motion: stillTextMotion(),
+ }],
+ });
+ const material: CompositableSurfaceRef = {
+ contract: "svml.compositable-surface@1",
+ artifact: { kind: "blob", digest: digestOf("text-mask-material"), size: 1, mediaType: "image/png" },
+ width: 800, height: 240, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
+ };
+ const track = renderTextMaskTrack(space, program, material, sealTextMaskSpec({
+ contract: "svml.text-mask-spec@1", id: "masked-title", mode: "alpha", materialFit: "cover",
+ }));
+ assert.equal(track.id, "masked-title");
+ assert.deepEqual(track.presents[0]?.elements.map((element) => element.kind), ["mask", "text", "surface"]);
+ assert.equal(track.presents[0]?.elements[2]?.parent, "mask");
+ const html = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "owned-mask-composition",
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [track],
+ }), space).html;
+ assert.match(html, /<foreignObject/u);
+ assert.match(html, />OWNED MASK</u);
+ assert.match(html, /mask-type:alpha/u);
+ assert.throws(() => renderTextMaskTrack(space, program, {
+ ...material, artifact: { ...material.artifact, mediaType: "video/webm" },
+ timing: { kind: "frames", frameCount: 150, frameRate: { numerator: 30, denominator: 1 } },
+ }, sealTextMaskSpec({
+ contract: "svml.text-mask-spec@1", id: "timed-mask", mode: "alpha", materialFit: "cover",
+ })), /requires one explicit still material Surface/u);
+ assert.throws(() => renderTextMaskTrack(space, sealTextTrackProgram({
+ ...program,
+ id: "advanced-mask-shape",
+ items: program.items.map((item) => ({
+ ...item,
+ style: { ...item.style, area: { ...item.style.area, overflow: "shrink", minimumScale: 0.7 } },
+ })),
+ }), material, sealTextMaskSpec({
+ contract: "svml.text-mask-spec@1", id: "advanced-mask", mode: "alpha", materialFit: "cover",
+ })), /must be materialized by an independent package/u);
+});
+
+test("TextTrackProgram rejects a frame span outside ProgramSpace", () => {
const program = sealTextTrackProgram({
contract: "svml.text-track-program@1",
id: "invalid-text",
items: [{
id: "late",
- text: "Too late",
+ sourceOccurrenceId: "program",
span: { startFrame: 149, endFrameExclusive: 151 },
- z: 1,
tieBreak: "late",
- frame: { contract: "svml.spatial-frame@1", xPx: 0, yPx: 0, widthPx: 1080, heightPx: 192 },
- appearance: { color: "#ffffff", fontSizePx: 24 },
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 0, yPx: 0, widthPx: 1080, heightPx: 192 } },
+ document: document("Too late"),
+ style: textStyle("late"),
+ motion: stillTextMotion(),
}],
});
assert.throws(() => renderTextTrack(space, program), /outside ProgramSpace/u);
});
-test("a selected Text Item is located only through explicit Selection and SemanticMap edges", () => {
- const mapContent = {
- contract: "svml.complete-semantic-map@1" as const,
- segments: [{
- segmentId: "opening", startSec: 0, endSec: 3, startFrame: 0, endFrame: 90,
- }],
- tokens: [0, 1, 2].map((index) => ({
- tokenId: `token-${index}`,
- segmentId: "opening",
- startSec: index,
- endSec: index + 1,
- startFrame: index * 30,
- endFrame: (index + 1) * 30,
- })),
- anchors: [0, 1, 2].flatMap((index) => [
- { identity: `segment:opening:token:${index + 1}:start`, timeSec: index, frame: index * 30 },
- { identity: `segment:opening:token:${index + 1}:end`, timeSec: index + 1, frame: (index + 1) * 30 },
- ]),
+test("Selection Text consumes explicit Selection, SemanticMap, Style, Motion and Placement edges", () => {
+ const map: CompleteSemanticMap = {
+ contract: "svml.complete-semantic-map@1",
+ tokens: [],
+ anchors: [
+ { identity: "selection:start", timeSec: 1, frame: 30 },
+ { identity: "selection:end", timeSec: 2, frame: 60 },
+ ],
};
- const map: CompleteSemanticMap = mapContent;
- const selectionContent = {
- contract: "svml.narrative-selection@1" as const,
+ const selection: NarrativeSelectionRef = {
+ contract: "svml.narrative-selection@1",
id: "callout",
- occurrences: [{
- occurrence: 1,
- startAnchorId: "segment:opening:token:2:start",
- endAnchorId: "segment:opening:token:2:end",
- }],
+ occurrences: [{ occurrence: 1, startAnchorId: "selection:start", endAnchorId: "selection:end" }],
};
- const selection: NarrativeSelectionRef = selectionContent;
const header = sealTextTrackHeader({ contract: "svml.text-track-header@1", id: "selected-text" });
const spec = sealTextItemSpec({
contract: "svml.text-item-spec@1",
id: "meaning",
- text: "MEANING",
- z: 80,
- appearance: { color: "#ffffff", fontSizePx: 48 },
+ document: document("MEANING"),
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ expansion: { kind: "one" },
});
- const program = finalizeTextTrack(header, appendSelectedTextItem(
+ const program = finalizeTextTrack(header, appendSelectionTextItem(
createTextTrackSet(),
header,
map,
selection,
space,
- { contract: "svml.spatial-frame@1", xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 },
+ bindAreaTextPlacement({ contract: "svml.spatial-frame@1", xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 }),
spec,
+ textStyle("meaning", 80),
+ stillTextMotion(),
));
assert.deepEqual(program.items.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 60 }]);
});
+
+test("the self-described Text Surfaces compile Style, Motion and all three spatial forms", async () => {
+ const fixtureModule = { name: "example.text-inputs", version: "1" } as const;
+ const fixtureDigest = digestOf("example.text-inputs/surface@1");
+ const fixtureManifest: ModuleManifest = {
+ format: "svml.module@1",
+ name: fixtureModule.name,
+ version: fixtureModule.version,
+ dependencies: [
+ programSpaceDependency,
+ spatialDependency,
+ mediaDependency,
+ {
+ module: { name: svsManifest.name, version: svsManifest.version },
+ digest: computeModuleDigest(svsManifest),
+ },
+ ],
+ types: [],
+ capabilities: [],
+ surfaces: [{
+ name: "inputs",
+ tag: "Inputs",
+ mode: "structured",
+ outputs: [
+ svsRecipeType,
+ programSpaceTypes.programSpace,
+ spatialTypes.point,
+ spatialTypes.frame,
+ spatialTypes.path,
+ mediaTypes.fontArtifact,
+ mediaTypes.compositableSurface,
+ ],
+ implementation: { kind: "trusted-frontend-surface", locator: "example.text-inputs/surface", digest: fixtureDigest },
+ }],
+ producers: [],
+ };
+ const closure = createResolvedClosure([
+ ...videoContractManifests,
+ svsManifest,
+ textTrackManifest,
+ fixtureManifest,
+ ]);
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerStructured(fixtureModule, "inputs", fixtureDigest, ({ element }) => ({
+ records: [
+ {
+ id: "editorial",
+ type: svsRecipeType,
+ value: { kind: "inline", value: {
+ contract: "svml.svs-recipe@1",
+ path: "text.editorial",
+ properties: {
+ "stack-order": 70,
+ size: 44,
+ "line-height": 1.15,
+ "inline-size": "fixed",
+ "block-size": "fixed",
+ wrap: "word",
+ overflow: "shrink",
+ "minimum-scale": 0.65,
+ },
+ } },
+ range: element.range,
+ },
+ {
+ id: "mask-editorial",
+ type: svsRecipeType,
+ value: { kind: "inline", value: {
+ contract: "svml.svs-recipe@1",
+ path: "text.mask-editorial",
+ properties: {
+ "stack-order": 75,
+ size: 100,
+ "line-height": 1,
+ "inline-size": "fixed",
+ "block-size": "fixed",
+ wrap: "none",
+ overflow: "visible",
+ },
+ } },
+ range: element.range,
+ },
+ { id: "space", type: programSpaceTypes.programSpace, value: { kind: "inline", value: space }, range: element.range },
+ { id: "title-point", type: spatialTypes.point, value: { kind: "inline", value: { contract: "svml.spatial-point@1", xPx: 540, yPx: 120 } }, range: element.range },
+ { id: "body-frame", type: spatialTypes.frame, value: { kind: "inline", value: { contract: "svml.spatial-frame@1", xPx: 80, yPx: 220, widthPx: 920, heightPx: 520 } }, range: element.range },
+ { id: "arc", type: spatialTypes.path, value: { kind: "inline", value: { contract: "svml.spatial-path@1", commands: [
+ { kind: "move", xPx: 120, yPx: 900 },
+ { kind: "cubic", control1X: 360, control1Y: 760, control2X: 720, control2Y: 1_040, xPx: 960, yPx: 900 },
+ ] } }, range: element.range },
+ { id: "exact-font", type: mediaTypes.fontArtifact, value: { kind: "inline", value: exactTestFont }, range: element.range },
+ { id: "material", type: mediaTypes.compositableSurface, value: { kind: "inline", value: exactTestSurface }, range: element.range },
+ ],
+ components: [],
+ fragments: [],
+ }));
+ surfaces.registerStructured(textTrackModuleRef, "style", textTrackSurfaceImplementationDigests.style, decodeTextStyleSurface);
+ surfaces.registerStructured(textTrackModuleRef, "motion", textTrackSurfaceImplementationDigests.motion, decodeTextMotionSurface);
+ surfaces.registerStructured(textTrackModuleRef, "track", textTrackSurfaceImplementationDigests.track, decodeTextTrackSurface);
+ surfaces.registerStructured(textTrackModuleRef, "mask", textTrackSurfaceImplementationDigests.mask, decodeTextMaskSurface);
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({
+ registry: surfaces,
+ resolveModule: (request) => request.from === "example.text-inputs@1" ? fixtureModule : textTrackModuleRef,
+ }));
+ const validators = new TypeValidatorRegistry();
+ registerTypeValidatorFacets(validators, spatialComponent.validators ?? []);
+ const compiled = await compileSourceClosure({
+ entry: {
+ id: "/project/text.svml",
+ name: "text.svml",
+ text: `<?svml using="@narratage/text@1"?>
+ <svml>
+ <import as="fixture" from="example.text-inputs@1"/>
+ <import as="text" from="@narratage/text-track@1"/>
+ <fixture:Inputs/>
+ <text:Style id="poster" recipe={editorial} font={exact-font}>
+ <text:Fill color="#f8fafc"/>
+ <text:Stroke color="#111827" width="3" placement="outside"/>
+ <text:Box target="line" continuity="isolated" color="#2563eb" padding="5 10" radius="8"/>
+ </text:Style>
+ <text:Style id="mask-shape-style" recipe={mask-editorial} font={exact-font}>
+ <text:Fill color="#ffffff"/>
+ </text:Style>
+ <text:Motion id="arrive">
+ <text:ItemKeyframe at="0" y="24" opacity="0"/>
+ <text:ItemKeyframe at="150" y="0" opacity="1"/>
+ <text:Sequence id="words" unit="word" start-index="0" end-index="2" duration-frames="12" stagger-frames="3">
+ <text:Keyframe at="0" opacity="0"/>
+ <text:Keyframe at="1" opacity="1"/>
+ </text:Sequence>
+ </text:Motion>
+ <text:Track id="titles" space={space}>
+ <text:Point id="hook" placement={title-point} style={poster} during="program">Hello world</text:Point>
+ <text:Area id="body" placement={body-frame} style={poster} motion={arrive} during="program">
+ <text:P id="first">Rich <text:Span style={poster}>inline text</text:Span><text:Break/>wraps.</text:P>
+ </text:Area>
+ <text:Path id="arc-title" placement={arc} style={poster} during="program">Along the path</text:Path>
+ </text:Track>
+ <text:Track id="mask-shape" space={space}>
+ <text:Area id="mask-word" placement={body-frame} style={mask-shape-style} during="program">MASK</text:Area>
+ </text:Track>
+ <text:Mask id="masked-titles" space={space} text={mask-shape.program} material={material}/>
+ </svml>`,
+ },
+ closure,
+ frontends,
+ admitRecord: createRecordAdmitter(validators),
+ resolveSource() { throw new Error("Text fixture has no source imports."); },
+ });
+ const program = resolveCompiledSourceExport(compiled, "mask-shape.program", textTrackTypes.program);
+ const ordinaryTrack = resolveCompiledSourceExport(compiled, "titles.track", compositionTypes.visualTrack);
+ const track = resolveCompiledSourceExport(compiled, "masked-titles.track", compositionTypes.visualTrack);
+ assert.equal(program.ref.kind, "logical-output");
+ assert.equal(ordinaryTrack.ref.kind, "logical-output");
+ assert.equal(track.ref.kind, "logical-output");
+ const build = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
+ graph: compiled.elaboration.graph.id,
+ targets: [
+ { output: ordinaryTrack.ref.kind === "logical-output" ? ordinaryTrack.ref.id : "", accepts: "exact" },
+ { output: track.ref.kind === "logical-output" ? track.ref.id : "", accepts: "exact" },
+ ],
+ satisfactions: [],
+ }));
+ const producers = build.plan.steps.map((step) => step.producer.name);
+ assert.equal(producers.filter((name) => name === textTrackProducers.bindPoint.name).length, 1);
+ assert.equal(producers.filter((name) => name === textTrackProducers.bindArea.name).length, 2);
+ assert.equal(producers.filter((name) => name === textTrackProducers.bindPath.name).length, 1);
+ assert.equal(producers.filter((name) => name === textTrackProducers.render.name).length, 1);
+ assert.equal(producers.filter((name) => name === textTrackProducers.renderMask.name).length, 1);
+});
+
+test("rich Text lowers ordered glyph layers, boxes, bounded flow, sequences and Path Text", () => {
+ const base = textStyle("rich", 75);
+ const rich = sealTextStyle({
+ ...base,
+ typography: {
+ ...base.typography,
+ language: "en",
+ trackingPx: 1.5,
+ decorations: [{
+ line: "underline", paint: { kind: "solid", color: "#facc15" },
+ style: "wavy", thicknessPx: 2, offsetPx: 4, skipInk: true,
+ }],
+ },
+ paints: [
+ { kind: "shadow", paint: { kind: "solid", color: "#2563eb" }, offsetX: 7, offsetY: 6, blurPx: 3, spreadPx: 1 },
+ { kind: "stroke", paint: { kind: "solid", color: "#ef4444" }, widthPx: 5, placement: "outside" },
+ { kind: "fill", paint: { kind: "linear-gradient", angleDeg: 30, stops: [
+ { offset: 0, color: "#ffffff", opacity: 1 },
+ { offset: 1, color: "#a7f3d0", opacity: 1 },
+ ] } },
+ { kind: "stroke", paint: { kind: "solid", color: "#fde047" }, widthPx: 2, placement: "inside" },
+ { kind: "shadow", paint: { kind: "solid", color: "#16a34a" }, offsetX: -4, offsetY: 3, blurPx: 0, spreadPx: 0 },
+ { kind: "glow", paint: { kind: "solid", color: "#e879f9" }, blurPx: 8, spreadPx: 2 },
+ {
+ kind: "box", target: "line", continuity: "isolated",
+ decoration: {
+ fill: { kind: "radial-gradient", center: { x: 0.5, y: 0.5 }, stops: [
+ { offset: 0, color: "#172554", opacity: 0.9 },
+ { offset: 1, color: "#020617", opacity: 0.9 },
+ ] },
+ paddingPx: { top: 4, right: 8, bottom: 4, left: 8 },
+ radiiPx: { topLeft: 8, topRight: 8, bottomRight: 8, bottomLeft: 8 },
+ shadows: [],
+ },
+ },
+ {
+ kind: "box", target: "word", continuity: "isolated",
+ decoration: {
+ paddingPx: { top: 1, right: 2, bottom: 1, left: 2 },
+ radiiPx: { topLeft: 2, topRight: 2, bottomRight: 2, bottomLeft: 2 },
+ shadows: [],
+ },
+ },
+ ],
+ area: { ...base.area, overflow: "shrink", maxLines: 3, minimumScale: 0.6 },
+ });
+ const pathStyle = sealTextStyle({
+ ...base,
+ id: "path",
+ paints: [{ kind: "fill", paint: { kind: "radial-gradient", center: { x: 0.5, y: 0.5 }, stops: [
+ { offset: 0, color: "#ffffff", opacity: 1 },
+ { offset: 1, color: "#38bdf8", opacity: 1 },
+ ] } }],
+ });
+ const motion = sealTextMotion({
+ contract: "svml.text-motion@1",
+ id: "sequenced",
+ item: { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(20px)" }] },
+ { atFrame: 150, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
+ ] },
+ sequences: [
+ {
+ id: "words", unit: "word", range: { start: 0, endExclusive: 3 }, order: "reverse",
+ startFrame: 0, unitDurationFrames: 20, staggerFrames: 4, cycles: 1,
+ keyframes: [
+ { atProgress: 0, style: [{ name: "opacity", value: 0 }, { name: "transform", value: "scale(0.7)" }] },
+ { atProgress: 1, easing: "ease-out", style: [{ name: "opacity", value: 1 }, { name: "transform", value: "scale(1)" }] },
+ ],
+ },
+ {
+ id: "lines", unit: "line", range: { start: 0, endExclusive: 2 }, order: "forward",
+ startFrame: 20, unitDurationFrames: 15, staggerFrames: 5, cycles: 1,
+ keyframes: [
+ { atProgress: 0, style: [{ name: "opacity", value: 0 }] },
+ { atProgress: 1, style: [{ name: "opacity", value: 1 }] },
+ ],
+ },
+ ],
+ });
+ const pathMotion = sealTextMotion({
+ contract: "svml.text-motion@1", id: "path-motion", sequences: [],
+ pathMargin: { keyframes: [{ atFrame: 0, startMarginPx: 0 }, { atFrame: 150, startMarginPx: 120, easing: "ease-in-out" }] },
+ });
+ const track = renderTextTrack(space, sealTextTrackProgram({
+ contract: "svml.text-track-program@1",
+ id: "rich-text",
+ items: [
+ {
+ id: "area", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "area",
+ geometry: { kind: "area", frame: { contract: "svml.spatial-frame@1", xPx: 80, yPx: 200, widthPx: 720, heightPx: 320 } },
+ document: { paragraphs: [{
+ id: "p1",
+ inlines: [
+ { kind: "text", id: "latin", text: "Intent stays " },
+ { kind: "text", id: "cjk", text: "可见", language: "zh-Hans", style: { typography: { weight: 400 } } },
+ { kind: "break", id: "break" },
+ { kind: "text", id: "rtl", text: "مرحبا 👩🏽‍💻 e\u0301", language: "ar", direction: "rtl" },
+ ],
+ }] },
+ style: rich,
+ motion,
+ },
+ {
+ id: "path", sourceOccurrenceId: "program", span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "path",
+ geometry: { kind: "path", path: { contract: "svml.spatial-path@1", commands: [
+ { kind: "move", xPx: 100, yPx: 700 },
+ { kind: "quadratic", controlX: 540, controlY: 520, xPx: 980, yPx: 700 },
+ ] } },
+ document: document("Renderer-neutral Path Text"),
+ style: pathStyle,
+ motion: pathMotion,
+ },
+ ],
+ }));
+ const rendered = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1", id: "rich-text-film",
+ canvas: { width: 1080, height: 900, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ assert.match(rendered.html, /data-svml-text-paint-layer="5"/u);
+ assert.match(rendered.html, /feMorphology/u);
+ assert.match(rendered.html, /linear-gradient\(30deg/u);
+ assert.match(rendered.html, /radial-gradient/u);
+ assert.match(rendered.html, /data-svml-text-overflow="shrink"/u);
+ assert.match(rendered.html, /data-svml-text-line-sequences/u);
+ assert.match(rendered.html, /<textPath/u);
+ assert.match(rendered.html, /data-svml-text-path-margin/u);
+});
diff --git a/packages/visual-ir/src/style.ts b/packages/visual-ir/src/style.ts
index 2d6bd530..abf606b1 100644
--- a/packages/visual-ir/src/style.ts
+++ b/packages/visual-ir/src/style.ts
@@ -68,6 +68,7 @@ export const VISUAL_STYLE_NAMES_V1 = [
"clip-path",
"color",
"column-gap",
+ "column-count",
"direction",
"display",
"filter",
@@ -78,9 +79,13 @@ export const VISUAL_STYLE_NAMES_V1 = [
"flex-shrink",
"flex-wrap",
"font-family",
+ "font-feature-settings",
+ "font-kerning",
"font-size",
"font-style",
"font-synthesis",
+ "font-variant-caps",
+ "font-variation-settings",
"font-weight",
"gap",
"grid-area",
@@ -119,6 +124,7 @@ export const VISUAL_STYLE_NAMES_V1 = [
"padding-left",
"padding-right",
"padding-top",
+ "paint-order",
"perspective",
"perspective-origin",
"position",
@@ -129,10 +135,14 @@ export const VISUAL_STYLE_NAMES_V1 = [
"text-decoration-color",
"text-decoration-thickness",
"text-overflow",
+ "text-indent",
+ "text-orientation",
+ "text-spacing-trim",
"text-shadow",
"text-transform",
"text-underline-offset",
"top",
+ "tab-size",
"transform",
"transform-origin",
"transform-style",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5d26119b..3161d422 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
'@narratage/composition':
specifier: workspace:*
version: link:packages/composition
+ '@narratage/deck-track':
+ specifier: workspace:*
+ version: link:packages/deck-track
'@narratage/estimate':
specifier: workspace:*
version: link:packages/estimate
@@ -83,6 +86,9 @@ importers:
'@narratage/provider-whisperx-local':
specifier: workspace:*
version: link:packages/provider-whisperx-local
+ '@narratage/ranking':
+ specifier: workspace:*
+ version: link:packages/ranking
'@narratage/render-hyperframes':
specifier: workspace:*
version: link:packages/render-hyperframes
@@ -487,6 +493,48 @@ importers:
specifier: workspace:*
version: link:../credential-store-env
+ packages/deck-track:
+ dependencies:
+ '@narratage/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
+ '@narratage/composition':
+ specifier: workspace:*
+ version: link:../composition
+ '@narratage/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@narratage/media':
+ specifier: workspace:*
+ version: link:../media
+ '@narratage/media-track':
+ specifier: workspace:*
+ version: link:../media-track
+ '@narratage/narrative':
+ specifier: workspace:*
+ version: link:../narrative
+ '@narratage/program-space':
+ specifier: workspace:*
+ version: link:../program-space
+ '@narratage/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@narratage/semantic-map':
+ specifier: workspace:*
+ version: link:../semantic-map
+ '@narratage/spatial':
+ specifier: workspace:*
+ version: link:../spatial
+ '@narratage/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@narratage/temporal':
+ specifier: workspace:*
+ version: link:../temporal
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
+
packages/driver-node:
dependencies:
'@narratage/component-kit':
@@ -1660,6 +1708,48 @@ importers:
specifier: workspace:*
version: link:../driver-node
+ packages/ranking:
+ dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
+ '@narratage/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
+ '@narratage/composition':
+ specifier: workspace:*
+ version: link:../composition
+ '@narratage/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@narratage/media':
+ specifier: workspace:*
+ version: link:../media
+ '@narratage/narrative':
+ specifier: workspace:*
+ version: link:../narrative
+ '@narratage/program-space':
+ specifier: workspace:*
+ version: link:../program-space
+ '@narratage/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@narratage/semantic-map':
+ specifier: workspace:*
+ version: link:../semantic-map
+ '@narratage/spatial':
+ specifier: workspace:*
+ version: link:../spatial
+ '@narratage/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@narratage/temporal':
+ specifier: workspace:*
+ version: link:../temporal
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
+
packages/render-hyperframes:
dependencies:
'@narratage/component-kit':
@@ -2166,6 +2256,9 @@ importers:
'@narratage/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@narratage/media':
+ specifier: workspace:*
+ version: link:../media
'@narratage/narrative':
specifier: workspace:*
version: link:../narrative
diff --git a/spec/deck-track.md b/spec/deck-track.md
index e6d4f74b..e679d96f 100644
--- a/spec/deck-track.md
+++ b/spec/deck-track.md
@@ -1,8 +1,8 @@
# SVML Depth-Stack Deck Track
-Status: design authority for the official depth-stack Deck migration. It records the behavior used
-by the old Deck implementation, but it is not a frozen public ABI and does not define a universal
-Deck protocol.
+Status: implemented executable authority for the official depth-stack Deck migration. It records
+the behavior used by the old Deck implementation, but it is not a frozen public ABI and does not
+define a universal Deck protocol.
## 1. Conclusion
@@ -264,6 +264,13 @@ Retire:
7. prove still and timed inactive-playback behavior;
8. migrate one real old-system Deck and freeze only after the acceptance matrix passes.
+Steps 1–8 execute in `@narratage/deck-track`. Package tests cover every state, validation,
+playback, label and extension case below. The real HyperFrames witness renders a Twinit-style
+three-Card depth stack twice—one worker and three partitioned workers—and compares every decoded
+frame byte-for-byte while also proving each authored current state paints. This completes the Deck
+package acceptance matrix; the terminal VisualTrack/Visual IR waist remains pre-freeze until the
+generic E1–E8 freeze criteria are all complete.
+
Required evidence includes:
- previous-only, next-only and mixed neighborhoods;
diff --git a/spec/ranking-track.md b/spec/ranking-track.md
index ca728130..b439a5d0 100644
--- a/spec/ranking-track.md
+++ b/spec/ranking-track.md
@@ -1,8 +1,9 @@
# SVML Ranking Track Migration
-Status: normative design for the official Ranking migration. It records the author model and
-lowering laws to implement after the shared temporal projection package. It is not a compatibility
-promise for the historical Twinit node format or a frozen public ABI.
+Status: implemented executable authority for the official Ranking migration. All four author
+components, their shared triggered schedule, optional peer AudioTrack lowering, author Surfaces and
+real-browser evidence execute in `@narratage/ranking`. It is not a compatibility promise for the
+historical Twinit node format or a frozen public ABI.
## 1. What Ranking means
@@ -268,16 +269,16 @@ Ranking branch and its temporal/media ancestors. No special Ranking execution ru
## 9. Migration order and acceptance
-Implementation order:
+Implemented in this order:
-1. implement the shared temporal projection and triggered-schedule laws;
-2. create `@narratage/ranking@1` with four separate Programs/Styles and one private schedule utility;
-3. lower TierBoard and Column first, because together they prove cumulative and exclusive stage
+1. **Implemented:** the shared temporal projection and triggered-schedule laws;
+2. **Implemented:** `@narratage/ranking@1` with four separate Programs/Styles and one private schedule utility;
+3. **Implemented:** TierBoard and Column, which together prove cumulative and exclusive stage
semantics plus independent stacking;
-4. lower TopThree;
-5. lower TypewriterList using exact font/layout primitives;
-6. add optional AudioTrack lowering from the same schedule;
-7. add real-browser visual witnesses and one author-Surface graph check per component.
+4. **Implemented:** TopThree;
+5. **Implemented:** TypewriterList using exact font/layout primitives;
+6. **Implemented:** optional AudioTrack lowering from the same schedule;
+7. **Implemented:** a real-browser progressive-state witness and one author-Surface graph check per component.
Acceptance requires:
@@ -295,3 +296,8 @@ Acceptance requires:
The migration intentionally does not preserve historical node JSON, mode switching, old dynamic
ports, renderer ids or Remotion components. Historical projects are evidence and visual references,
not a compatibility obligation for an unreleased language.
+
+The package test matrix covers every acceptance item above. The opt-in Chromium witness evaluates
+all four components with one worker and partitioned workers, proves visible trigger progression and
+the final settled suffix, and bounds only microscopic cross-process edge-antialiasing noise. Logical
+frame state, geometry, stacking, event frames and authored graph edges remain exact.
diff --git a/spec/spatial-layout.md b/spec/spatial-layout.md
index aae1a285..1f16b06a 100644
--- a/spec/spatial-layout.md
+++ b/spec/spatial-layout.md
@@ -2,8 +2,8 @@
Status: executable foundational authority for shared Spatial geometry. `@narratage/spatial`
implements CanvasSpace, Frame/Point/Path, IntrinsicExtent, ContentFit and pure fitting; Film now
-consumes the same explicit CanvasSpace as Track layout. Text, Media and Ranking migration witnesses
-and the public ABI freeze remain incomplete.
+consumes the same explicit CanvasSpace as Track layout. Text, Media and all four Ranking migration
+witnesses execute; only the final shared Visual IR compatibility audit and public ABI freeze remain.
## 1. Conclusion
@@ -437,9 +437,10 @@ Retired:
2. **Implemented:** split Canvas declaration from Film assembly and connect the same Canvas value to Track layout and
Composition;
3. **Implemented:** migrate one simple Text Area and one simple Media still image through shared geometry;
-4. add exact browser tests for every fit and alignment law;
-5. prove ordered transparent/color/self-blur/alternate-source Media layers;
-6. migrate Ranking and Comment Sticker geometry;
+4. **Implemented:** add exact browser tests for every fit and alignment law;
+5. **Implemented:** prove ordered transparent/color/self-blur/alternate-source Media layers;
+6. **Implemented:** migrate all four Ranking components through explicit shared Frames; Comment
+ Sticker remains deferred until it has its own design;
7. only then freeze the Spatial Types and related Visual IR behavior.
The test matrix must include:
@@ -456,5 +457,10 @@ The test matrix must include:
- rounding/raster behavior locked by the selected renderer implementation;
- no Core, Runtime, Film-family, Text-family or Media-family discriminator in the shared Types.
-Until those witnesses pass, percentages embedded independently in Text, B-roll and Caption remain
-migration scaffolding rather than the shared spatial system.
+The pure geometry matrix and real Chromium witness now cover every sizing mode, all nine equal-point
+alignments, unequal bounded/free focal points and partially/fully off-Canvas Frames. Media
+normalization additionally materializes container rotation and non-square sample aspect into a
+square-pixel visual before deriving `IntrinsicExtent`. Ranking now consumes the same explicit Frame
+geometry without adding a family discriminator. Spatial remains pre-freeze until the final Visual IR
+compatibility audit passes; no package-local percentage vocabulary should grow in
+the meantime.
diff --git a/spec/text-track.md b/spec/text-track.md
index ac277665..1b5e70c9 100644
--- a/spec/text-track.md
+++ b/spec/text-track.md
@@ -1,8 +1,8 @@
# Text Track Authoring and Expressiveness
-Status: design authority for the official two-dimensional Text migration. The current
-`@narratage/text-track` package is an executable vertical slice, not an implementation of this
-complete model. The terminal Visual IR changes identified here remain pre-freeze work.
+Status: implemented pre-release authority for the official two-dimensional Text package. The
+complete declared model and browser evidence execute through the candidate Visual IR; the shared
+Track/renderer ABI remains pre-freeze work.
## 1. Conclusion
@@ -149,6 +149,11 @@ Those may be separate packages or separately imported components in a later offi
Package count is a distribution decision; their graph contracts must remain separate. Neither case
adds a branch to Core.
+The official local Text Mask witness deliberately accepts only one exact single-line Area Text
+shape and one explicit still `CompositableSurface`. Rich runs, multiline/Path flow, sequence
+animation and timed materials fail closed and use the same materialized-Surface escape route as 3D
+Text. This boundary avoids pretending that browser `foreignObject` masking is portable or exact.
+
## 4. Authored Text Document
A Text item consumes a bounded rich document rather than an HTML fragment or arbitrary tree:
@@ -414,25 +419,21 @@ or package-owned resolved geometry used to materialize a Surface.
## 11. Terminal Visual IR findings
-The current `svml.visual-ir@1` candidate can already carry simple nested boxes, exact fonts, local
-style keyframes and duplicated glyph layers. It is not yet sufficient to honestly freeze the Text
-model:
+The candidate `svml.visual-ir@1` now carries the smallest additions proven by this migration:
-- one `text` element is one escaped leaf string, so interleaved rich runs and paragraph structure
- have no first-class terminal representation;
-- there is no vector path/text-path primitive;
-- local masks are not represented;
-- keyframes can animate only opacity, transform, filter and clip-path, not sequenced glyph Paint;
-- the closed style vocabulary lacks several typography controls;
-- repeated Paint layers and their ordering are only implicit renderer tricks.
+- `text-flow` owns the bounded rich document, exact typography, ordered Paint and sequence values;
+- `path-text` owns typed vector commands and exact path-flow facts;
+- the local `mask` primitive owns exactly one terminal mask source and one content root;
+- ordered repeated Paint and Unicode unit animation remain serialized data, never callbacks;
+- exact font Artifacts and typed `CompositableSurface` values cross the ordinary Artifact boundary.
-These are video-terminal issues, never Core issues. Before Visual IR freezes, implementation must
-choose and prove the smallest renderer-neutral additions for rich text flow, typed local masking,
-path geometry and unit-local animation. A capability that still cannot be expressed uses the
-existing typed `CompositableSurface` path.
+The HyperFrames reference compiler implements those primitives without exposing HTML, CSS, SVG or
+renderer scripts to author packages. A separately installed non-native Text fixture proves that
+extrusion/material/light/camera semantics can remain outside the waist and contribute only a typed
+alpha Surface. Unsupported rich masks use the same path.
-The requirement is not to expose HTML, CSS, SVG or renderer scripts. It is to add only generic
-code-free visual primitives with at least Text and one independent witness where practical.
+These remain video-terminal facts, never Core facts. Visual IR is still a candidate until renderer
+receipts, Surface-byte validation, Deck/Ranking witnesses and the final compatibility audit pass.
## 12. Feedback into Fine Caption
@@ -468,17 +469,16 @@ Atoms and activates only from proven Atom windows.
## 13. Migration order and acceptance gates
-Implementation should replace the current slice rather than accrete compatibility fields:
+Implementation replaced the earlier slice rather than accreting compatibility fields:
-1. define Text Document, Point/Area tagged geometry, Text Style and ordered Paint values;
-2. implement exact fonts, plain/phrase/line/word/grapheme Box Paint and rich-run static lowering;
-3. route every item through shared Temporal Window Projection and the specified shared Spatial
- source;
-4. add deterministic overflow, direction/writing mode and browser pixel evidence;
-5. add item motion and Unicode-aware sequence selectors;
-6. add Path Text and typed local mask support or materialized witnesses;
-7. prove the `CompositableSurface` escape route with one 3D or otherwise non-native Text package;
-8. only then decide the smallest Visual IR revision and freeze it.
+1. **Implemented:** Text Document, Point/Area tagged geometry, Text Style and ordered Paint values;
+2. **Implemented:** exact fonts, frame/content/paragraph/line/run/word/grapheme Box Paint and rich-run static lowering;
+3. **Implemented:** shared Temporal Window Projection and explicit Point/Frame/Path Spatial inputs;
+4. **Implemented:** deterministic overflow, direction/writing mode and browser pixel evidence;
+5. **Implemented:** item motion and Unicode-aware sequence selectors;
+6. **Implemented:** Path Text plus an exact bounded local Text Mask and fail-closed materialization boundary;
+7. **Implemented:** the `CompositableSurface` escape route with a separately installed non-native Text package witness;
+8. **Pending shared freeze:** settle the final Visual IR only after the repository-wide gates pass.
Acceptance requires browser/render evidence for at least:
@@ -493,5 +493,5 @@ Acceptance requires browser/render evidence for at least:
- explicit Text Mask ownership and one materialized advanced fallback;
- no modification to Core, Runtime, Film or an unrelated Track package.
-Until those gates pass, the current Text package proves the graph path only and must not be
-described as a complete or frozen Text system.
+The declared Text package gates now pass. This establishes a complete pre-release Text package, not
+a frozen public Track or Visual IR compatibility promise.
diff --git a/spec/track-authoring.md b/spec/track-authoring.md
index 8fe77bee..8b3f9dbc 100644
--- a/spec/track-authoring.md
+++ b/spec/track-authoring.md
@@ -441,19 +441,21 @@ The first implementation batch must include tests for:
## 9. Ranking specialization
-The complete Ranking audit, component split, group schedule and migration plan are specified in
-[`ranking-track.md`](./ranking-track.md). Ranking validates that the common temporal algebra can
+The complete Ranking audit, component split, group schedule and executable migration are specified in
+[`ranking-track.md`](./ranking-track.md). Ranking now validates that the common temporal algebra can
support cumulative state, exclusive current stages and a final settled suffix without adding
Ranking or `Stage` meaning to Core or the public Track contract.
## 10. Remaining design and implementation work
-The following work remains, but it does not block rewriting packages whose own specifications and
-shared dependencies are complete:
+One independently designed author package remains outside the current migration:
1. design Comment Sticker content/layout/presentation independently when a real migration starts;
-2. implement the existing acceptance matrix proving all packages lower to peer
- VisualTrack/AudioTrack values without changing Core or Composition.
+
+For every currently specified official Track package, the implemented acceptance matrix proves
+Text, Caption, Media, Deck, Ranking and Screen Overlay lower to peer VisualTrack values, while
+generic Audio and optional Media/Ranking sound lower to peer AudioTrack values without changing
+Core or Composition.
Generic Audio Track and self-contained Screen Overlay are now specified separately in
[`audio-track.md`](./audio-track.md) and [`screen-overlay.md`](./screen-overlay.md). Audio reuses the
diff --git a/spec/track-expressiveness.md b/spec/track-expressiveness.md
index 9e9ebe21..664395aa 100644
--- a/spec/track-expressiveness.md
+++ b/spec/track-expressiveness.md
@@ -155,9 +155,11 @@ executable rather than package-family patches:
`packages/hyperframes/test/browser-visual.test.ts` additionally drives real Hyperframes browser
frames: installed content-addressed open fonts paint Latin, CJK and emoji/symbol glyphs through an ordered fallback
-stack; Fine Caption proves multiline wrapping, full glyph Paint, every glyph karaoke mode and joined
-trail Pill line geometry; all eleven official Screen Overlay components preserve identical pixels
-under sequential and parallel frame rendering; and a
+stack; Text proves Point/Area/Path layout, all Box targets, rich runs, horizontal/vertical flow,
+clip/ellipsis/bounded shrink, ordered Paint, local Mask and forward/reverse selector clocks; Fine
+Caption proves multiline wrapping, full glyph Paint, every glyph karaoke mode and joined trail Pill
+line geometry; DepthStack Deck proves explicit old/new collection-state reflow, exact labels and
+byte-identical one-worker/partitioned frames; all eleven official Screen Overlay components preserve identical pixels under sequential and parallel frame rendering; and a
50% straight-alpha PNG composites over a blue Track at the expected pixel values. This opt-in host
test is run with `SVML_BROWSER_TESTS=1`; it proves the current local renderer path, not every future
hosted Runtime.
@@ -169,11 +171,18 @@ candidate-era package migration, and a production Runtime still needs to bind it
implementation and validate that Surface bytes satisfy the declared metadata. Those remaining
facts must stay generic; they must not be patched with Caption-, Text- or Media-specific fields.
-E7 and E8 now have their official package witnesses. `@narratage/audio-track` proves the exact
+E1–E5, E7 and E8 now have their official package witnesses. `@narratage/text-track` proves the
+complete three-box/Text terminal model without public Text fields; Caption and Media prove their
+independent package models. `@narratage/audio-track` proves the exact
48 kHz source/target mapping, overlap law, bounded stretch and one shared local/remote
`AudioProgramPlan`; `@narratage/screen-overlay` proves only self-contained owned pixels, explicit
-seeds, flat stacking and fail-closed rejection of lower-composite effects. E1–E6 remain governed by
-the complete Text/Media/Deck work and final Surface validation below.
+seeds, flat stacking and fail-closed rejection of lower-composite effects;
+`@narratage/deck-track` proves pure absolute-frame collection reflow over the union of old/new
+visible Cards while reusing Card-local Media lowering. `@narratage/ranking` supplies the real E4
+witness: board, stage and independently stacked Items interleave with an unrelated peer Track,
+while all four Ranking components retain frame-pure progressive state under partitioned browser
+rendering. E6 alone awaits Runtime Surface-byte validation despite its typed path and independently
+installed non-native Text witness already executing.
## Freeze criteria
diff --git a/spec/visual-ir.md b/spec/visual-ir.md
index 65d8233d..48c79294 100644
--- a/spec/visual-ir.md
+++ b/spec/visual-ir.md
@@ -108,12 +108,13 @@ IR, not fields added to the IR.
## Remaining freeze gates
-The identifier and closed vocabulary are executable, but v1 remains a candidate until:
-
-1. the official Text lowerer requires exact font Artifacts or materialized glyph Surfaces; Fine
- Caption already exposes an exact ordered font stack while retaining an explicit prototype path;
-2. remaining old production Text/media witnesses have real browser pixel tests for their own
- multiline decoration, focal sampling, alpha and overflow; Fine Caption's CJK/emoji matrix is complete;
-3. the Runtime receipt binds the exact renderer implementation used for layout;
-4. Surface bytes are checked against their declared dimensions, timing, color and alpha facts;
-5. a separately installed Track package passes without changing Core, Film or HyperFrames code.
+The identifier and closed vocabulary are executable. Exact Text fonts, multiline decoration,
+Path/Mask/overflow, Media focal sampling and alpha now have real browser evidence; a separately
+installed non-native Text package crosses the typed Surface waist without changing Core, Film or
+HyperFrames. The candidate remains open until:
+
+1. the Runtime receipt binds the exact renderer implementation used for layout;
+2. Surface bytes are checked against their declared dimensions, timing, color and alpha facts;
+3. **Completed:** Deck and Ranking provide the remaining package-owned Track expressiveness witnesses;
+4. the final repository-wide compatibility audit proves that no package-family discriminator or
+ hidden cross-Track sampling path entered the waist.
diff --git a/tsconfig.json b/tsconfig.json
index 6fffac0f..3f7b31e9 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -42,6 +42,12 @@
"@narratage/media-track": [
"packages/media-track/src/index.ts"
],
+ "@narratage/deck-track": [
+ "packages/deck-track/src/index.ts"
+ ],
+ "@narratage/ranking": [
+ "packages/ranking/src/index.ts"
+ ],
"@narratage/speech": [
"packages/speech/src/index.ts"
],