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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: complete documented visual track packages
kashorin1bc03ee3ae5d
diff --git a/examples/talking-film-graph-check/main.svml b/examples/talking-film-graph-check/main.svmlindex 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.svsindex 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.lockindex 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.jsonindex 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.tsindex 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.tsindex 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 } fromexport { 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: { kindconst 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.tsindex 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): vfunction 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 | undecursor = 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.tsindex 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 domaintracks: [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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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): stringconst 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.tsnew file mode 100644index 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.tsindex 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, colufunction 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":"forward/u);+ assert.match(compiled.html, /order":"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.tsindex 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 witassert.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.tsindex 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): Mediarole: "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.tsindex 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 | undefinedreturn { 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.tsindex 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-streaassert.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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 MediaStassert(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.tsindex 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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, Pathsand 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 finiteconst 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 finiteentry: 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 finiteresolveSource() { 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 finitetargets: [{ 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.mdindex 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 everyitem 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. Theyare 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 inRecipe. The package exposes semantic typography rather than a rendering callback, arbitrary CSS orcross-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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.yamlindex 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:../narrativediff --git a/spec/deck-track.md b/spec/deck-track.mdindex 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.mdindex 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 stagesemantics 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 dynamicports, 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.mdindex 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 andComposition;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.mdindex 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 offiPackage count is a distribution decision; their graph contracts must remain separate. Neither caseadds 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 DocumentA 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.mdindex 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 cansupport cumulative state, exclusive current stages and a final settled suffix without addingRanking 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 thediff --git a/spec/track-expressiveness.md b/spec/track-expressiveness.mdindex 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 browserframes: 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 a50% straight-alpha PNG composites over a blue Track at the expected pixel values. This opt-in hosttest is run with `SVML_BROWSER_TESTS=1`; it proves the current local renderer path, not every futurehosted Runtime.@@ -169,11 +171,18 @@ candidate-era package migration, and a production Runtime still needs to bind itimplementation and validate that Surface bytes satisfy the declared metadata. Those remainingfacts 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 exact48 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 criteriadiff --git a/spec/visual-ir.md b/spec/visual-ir.mdindex 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.jsonindex 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"],