TRL `0.3.0-next.X` Release
Greets @FVTT ▹ Developer!
The initial
0.3.0-next.2 release is out for @typhonjs-fvtt/runtime and @typhonjs-fvtt/standard. This brings essential Foundry v13 / Theme V2 support to TRL. If you are already on 0.2.0 there should be no code changes required.
...unless you were using TJSTinyMCE / TinyMCE component as an editor. v13 soft locked it such that it is impossible to style w/ the new CSS layer changes to core without serious workarounds. Since MCE is disappearing in v14 I just removed it now. You'll need to switch to TJSProseMirror instead.
I have upgraded / fixed all Foundry integration points like the file picker components, Foundry sidebar modifications and such. If there is anything that you see that is not fixed let me know.
If you have added any temporary workarounds since v13 launched to get 0.2.0 to work on v13 you should remove them.
It may be handy to check out essential-svelte-esm for some CSS tricks on how to handle the dark / light theme changes for components you create. It also is a good demo of a large chunk of TRL functionality and various Foundry integration points. I have updated the repo with the 0.3.0-next.2 coverage / Foundry v13 is required.
Let's use this forum post to keep track of all 0.3.0 release information / questions.
----
The one outstanding aspect I need to complete before 0.3.0 officially launches is the dynamic style introspection layer of the standard library. Several of the standard library components like the input, select, color picker, buttons, etc. adopt the core platform styles dynamically at runtime. v13 has drastically changed how that works, so I need to rework the dynamic style introspection layer. I hope to be finished with that before end of next week.
If you must push out a package release now it might be required that you push out another release once the final 0.3.0 is released. While I do have mechanisms in place to update the introspection layer code it is possible this time around due to the nature of the changes that if you release now and don't make a release when 0.3.0 is out that there could be a conflict.
Usually, I try and get TRL ready to go out of the gate before core launches the next version into "stable". This time it's a bit late for various reasons.
A video showing some of what you should expect from 0.3.0:
https://www.youtube.com/watch?v=qVE4yH52jDMTyphonJS
YouTube
TRL / TyphonJS Runtime Library 0.3.0-next.1 Overview
This video gives an overview of what to expect for v13 / Theme V2 changes for TRL on Foundry v13.
0.3.0 requires Foundry v13 and you must recompile your packages for release. There shouldn't be any code changes from 0.2.0.
I demo some things from the essential svelte ESM demo repo. I did forget to demo the file pickers components. They are...42 Replies
I should mention that I have only updated
essential-svelte-esm the template repo and Typescript repos are not updated; just bump the TRL release in package.json as appropriate. Also the API docs will be updated on the final 0.3.0 release; there really aren't changes in the API.
@FVTT ▹ Developer... I'm making progress on the final CSS variable / v13 CSS Layer refactor. Things will work out nicely... However, I am considering a rework to the TRL dynamic style system such that it indexes / retrieves the styles by CSS ID instead of the old mechanism of adhoc storing a key on the document itself. A few other aspects changing as well which will make the dynamic style sheet more visible in the DOM like adding the version as a data attribute rather than a non-descript style entry in head.
This means the old mechanism and the new mechanism function differently.
If possible I'd like to get a count of how many of you have released packages for v13 with either 0.2.x or the 0.3.0-next.2 releases?
What this means moving forward is that everyone should do a release with 0.3.0 final or the next.3+ future beta releases forthcoming.I’ve updated a module to v13 using
Without any problems other than the window.MIN_WINDOW_WIDTH thing.
Without any problems other than the window.MIN_WINDOW_WIDTH thing.
Thanks for the response. You are really far behind by not updating to
0.2.x / IE some refactoring work ahead for you, mostly package sub-path changes. I do recommend that you get started now updating to 0.2.x. The swap to 0.3.0 will not have API changes from 0.2.x. Refer to the API Docs or ask questions in the 0.2.0 forum post.Still waiting for Svelte 5 to start a system dev. After migrating a dozen of projects to Svelte 5 and actively using it for months, it would be too painful to get back to Svelte 4 syntax
I agree. I'm looking forward to getting past the v13 hump and being able to focus on just TRL which is a somewhat more pleasant experience. It will still be a minute, but keeping up w/ the latest TRL release helps.
0.4.0 will be the last long-term Svelte 4 release on the latest toolchain.
Personally the drop off is quite apparent in the community; I wished all of this could happen quicker, but methodical and steady is my process. I think Svelte 5 is going to kill most folks packages unless they are dedicated devs. Too many devs pop in for an exploratory package jaunt, but it's real work to refactor / rework a package to the latest tech. Svelte 5 will be quite the cliff.I am eagerly waiting for it
If not just for the ability to use
{get(), set()} in the svelte markup for form inputsTypes is going to be a process / big focus, but good news is that since there is end to end support currently it's easier to A/B any new developments. Hopefully I'll be able to complete the circle w/ next-gen Svelte to provide a fully fine-grained Foundry document model wrapper as that opens hooking up Foundry documents to anything smoothly w/ Svelte. I avoided introducing hacks / quick fixes / hardcoding to the Foundry API.
Given the uncertain economy I'm skipping going to New Zealand for ski training / might have mentioned this earlier this year, so I'll be on this all through the summer here.
Folks staying active in the community here too helps quite a bit for motivation to keep grinding all of this out. One of things I could / can do better is highlight more the solid solutions in TRL and how Svelte provides better architecture solutions. When everything just works the time to make that so might be obscurred.
I've done something slightly naught even. I released a v12 module with trl 0.3-next
Everything kinda works as long as your UI is either fully custom or just non-fancy enough
That might work if you are using
TJSApplicationShell (TRL CSS vars + fallback) vs ApplicationShell (new ThemeV2 classes). The old dynamic styles are still running in next.2. I don't recommend it per se as it's not being tested and what you are seeing now might not be the case for the final 0.3.0 release.
So far v13 is the only core update that I haven't been able to have fully backward compatible where it was easy to release a package across versions in respect to UI aspects / mechanisms in TRL at least.my users are well informed that V12-V13 will be a compatibility barrier, I just figured I'd test the module in V12 anyway
So, I'm still finishing up some of the technical work, but certain it's all going to work out on that angle. Just want to post an update on some of the detailed work / examples of why the v13 update is taking some time. There are areas of TRL that probably don't get used much yet like the reactive document dialogs for create / update, etc. The attached brief video shows how the v13 changes affect those dialogs and they need to reworked. Hopefully in the future some of the system devs here will give them a whirl as they support modal dialogs which IMHO is a much better workflow around document creation / modification than potentially popping up hundreds of duplicate windows like the core platform does.
It's a big process to go through and manually verify everything that is in TRL, so while you / most might just use the app shells and call it a day and not use the extended set of TRL features there is just a lot of detailed work to update.
👀
Yeah... So I noticed the not so great (plenty to talk about here) context menu implementation in Foundry is now using the Popover API. This puts the context menu into a top layer above the main browser content.
This is over the current glasspane / modal implementation and context menu implementation in TRL. So things went mostly smoothly getting the glasspane and context menu implementation working in Chrome with the Popover API. Guess which browser I tried next.... FU Firefox! Not sure if it's something from CSS Layers + Popover API + maybe Svelte, but the CSS just wouldn't take in Firefox for elements with
popover compared to Chrome. Or... It's just janky Firefox. Tried many things for 8+ hours yesterday.
Woke up today / updated Firefox nightly and everything worked like it should and the egregious problem from yesterday is not present... Is there a :: pull hair out :: emoji?:vicksyAAAA:
But yeah, Firefox keeps having issues with CSS for my own websites
And thats just flex related stuff
Cant imagine using popover yet until wider compatibility
That'll do! I was just about to settle in for another battle session w/ FF and relieved to keep moving forward. It just made no sense and was super weird yesterday.
Yeah.. That's the thing about Foundry. It's OK to use the latest browser APIs for experimental efforts / not when building a stable platform... We all know "stable" in context of Foundry does not mean stable. So many things IMHO only make it to the 90% done level in Foundry; this is my charitable estimation. Problem is though you start piling all those almost done things on top of each other and keep changing things every release in areas that have no dev notes it's a PITA. The context menu implementation in core could be improved significantly with just a bit more attention to detail and handful of code changes.
I would wait until '26 and CSS anchor positioning hits baseline before depending on the Popover API.
To be fair though I spend 100% of my time at the application layer and get to put way more time into getting to 100% or closest possible. Foundry staff must be in "whack a mole" dev mode most of the time.
I would at least put "You are using an unsupported browser" popup if they were so adamant on being bleeding edge (while also using Handlebars)
I mean... the Popover API is not bleeding edge. It's been declared fully implemented by both major browser engines for over a year now
It's just that with waning userbase and missing funding, gecko is becoming less and less usable, which is making things worse
Right, its implemented, but its not all that great is what I was meaning to say. UI frameworks still use javascript in order to make modals and popovers due to compatibility issues between browsers and how unreliable or hard-coded these can be.
Yeah I feel that, I was about to remark that being stable in webdev feels like a loosing battle with how at mercy of partially buggy browser implementations you are
its honestly quite baffling to me that foundry isn't using any frontend library and are insisting on doing everything themselves
to me that'd be more trouble than its worth
They're oldschool in the literal sense of using tech from 2010
And only now modernizing it (likely due to publisher influence like WotC and Paizo)
But they are still rather standalone in their design patterns
Injecting interactivity into statically rendered handlebars (which is also being rendered on the client) is wild to me
I mean sure, I still use Jinja2 templates at work, but thats because i'm rendering static HTML on the server in python
Still, with all the weirdness going on, I feel like foundry is the best option on the market if you want to have any semblance of code customization
It is
Just shame it is a mile behind modern practices
Atropos himself admitted he doesnt know how React works
At least I finally got them to add a "streamReady" hook on the /stream page
I mean to be honest, I also don't know how react works, I've used it like twice in my life
But thats why I use svelte
Structurally, Foundry feels like its built like a game would be. Not like a webapp.
Having that complete separation between the actual rendering of the world and the UI. Both in layer and in implementation
While I never used it, I know the logic behind it
Svelte abstracts that logic into a much easier and neater syntax
I kinda comprehend the idea of virtual dom, that is true
But overall you still have a concept of reactive values that you keep track of, and if they change, you do something.
React just leaves you to it with updating the DOM if those values change.
Svelte just merges the two concepts into one coherent whole.
I also love that svelte syntax is closer to HTML
JSX feels weird to me
how stable is v0.3? currently using v0.2 in foundry v12 and v13 and I have no issues, I dont want to upgrade if it's unstable yet
The only early
0.3.0-next.2 is alpha level. Not broken, but not addressing all of the underlying problems of the theming / CSS layers / and conflicts in approach to theming that v13 brought to the table. The result of the core v13 styles is significantly increased complexity for consumers on the platform including TRL. A bunch of work / complexity^2 to reverse the platform complexity at runtime caused the delay, but all that has been successful.
The first stable / beta of 0.3.x is coming imminently (early this upcoming week). I've finished all of the major critical path work yesterday. I'm just updating all of the demo repos including verifying the TS ones before the 0.3.0-next.3 release.
0.3.x is for Foundry v13+ as the core platform drastically changed in areas that are not compatible across versions. So it is recommended to stay on 0.2.x for v12, but have a new package release for v13 using 0.3.x. Ones milleage may vary in that you don't see problems in your particular packages.
The remaining work to do before a final 0.3.0 release is mainly smoothing all of the theming aspects out for the standard library. If you are not using anything from the standard library then the 0.3.0-next.3 release is effectively stable. I don't expect too many changes to the runtime library before the 0.3.0 release; just work on the standard library to finish off seamless theming support for dark / light themes out of the box.
I will be posting several new demos to essential-svelte-esm for the final 0.3.0 release. Lots of neat new features including out of the box container query support in app shells which is super handy and powerful.Thnaks for the detailed answer Michael, as I'm using the sahdow realm to isolate from foundires own css fun I think I'm safe but I'l wait for the beta just to be on the safe side.
Thanks for all your hard work as always!
I appreciate it. This one was a bit rough as transparency was low from core changes and several external real world delays / impacts occurred at the same time which added about ~2 months of non-ideal concentration blockers to the challenging code I had to create to combat the shifts in the core platform.
All good, take your time, TRL has been very stable for me, I had 0 issues with it and my module is a full "mini-app" inside it with pages, tabs, login flow, user tiers, patreon integration so I can vouch it works flawlessly
btw, no rush I'm just wondering if you have a rough timeline for svelte 5 support? I was thinking about a few modules I wanted to create and I'm not sure if I should wait til svelte 5 comes around to TRL or just write it and migrate later
The general plan for
0.4.x is to get TRL to function on Svelte 5 in compatibility mode. TRL itself won't transition any code over to Svelte 5 except the bare minimum required. You can roughly expect your package sizes to drop by ~33% which is nice. The idea is to make 0.4.x the LTS Svelte 4 level version of TRL running on Svelte 5. It should be possible to write ones own additional code using Svelte 5. I plan to address getting the toolchain up to the latest Vite / support plugins and upgrading the ESLint infrastructure and adding ESLint support for Svelte components / TS.
I'd like to say 0.4.x will be out fairly quickly but just depends on any rough edges still in Svelte 5 that TRL might touch. Ideally this is all out in less than a month after 0.3.x. I have a strong suspicion that the new animation / transition support in Svelte 5 is not robust and we'll see some teething issues there that still need be resolved in Svelte 5 itself.
From there the major and complete overhaul of TRL for next-gen Svelte is planned for 0.5.x. This will dramatically change lots of things and be a pretty large demarcation line for those who have Svelte 4 based packages. Impacts may vary depending on what you use from TRL. This will be another long release cycle probably in the ~3+ month timeframe, but quite a few unknown unknowns there w/ timing.
So one last thing I'm trying to finish w/ the runtime stylesheet resolver has come up which I'd like to complete now. So a day or so delay more or less. An interesting problem which I should be able to complete tonight, but came up when fully applying resolution to the #runtime / application shell components. In this case that is url() resolution in regard to altering relative paths to absolute for local resources. With styles you can use relative paths from where the style file is located / served. The dynamic styles / TRL CSS variables inserted into the main / game page are based on the HREF of the game page. It is not possible to just copy a style property / CSS var that references url() to a TRL CSS var without accounting for any path changes.
Right now I have hardcoded paths for app background images which is fine for core dark / light theming as that likely won't change anytime soon for core. I'd really like to resolve these aspects though for potential core changes, but more appropriately for 3rd party theming.
The runtime stylesheet resolver needs an option to convert any relative paths to absolute based on the currently processed sheets base HREF in addition to handling route prefixes. Just going to take the rest of the evening sorting this out. This should be the last task for the very comprehensive solution I've put together for dynamic style management in TRL. Because this is a critical path in TRL and difficult problem to manage across multiple independent 3rd party packages using TRL I'm going for the complete solution out of the gate.
Phew... Got it done and it works great. Also significantly optimized about as far as you can go w/ JS. Full parse all stylesheets (core, dnd5e, +3 modules) w/ URL rewrite and applying resolution for TRL CSS vars is 80ms on my 6 year old box. This is only done once across multiple TRL packages by the CSS versioning. I'm going to really work hard to make sure the final 0.3.0 release is bulletproof and doesn't require bumps. I don't see any additional specific engineering work remaining. Just have to finish applying these last several weeks of work.But was it really done? After some sleep and yet again a fresh set of eyes something just intuitively felt off when viewing the performance metrics in the real world / browser / Foundry arrangement. When I implemented the initial url rewriting that brought the time up to 120ms and with broad reworking on the code for performance removing all unnecessary array copying via
filter() / map(), new object creation via fromEntries and converting over to "traditional" counter based for loops instead of for of loops I got things back down to 80ms. We got all of the filtered data that we set out to capture. But was it really done?
For the past ~2+ weeks I've been mostly developing this code against a local test suite that only ensures that functionally the code does what we want. There is no local stress / benchmark test, so over the last couple of days I've been analyzing performance in the real world / on Foundry use case. With the code understanding fresh in my mind and some additional intuition on actual expectations I kept digging and found a small code change I overlooked w/ the local tests. There were no bugs / issues w/ the data output of the code; it just didn't perform at peak expectations. If you haven't worked w/ performance tuning in the browser this video gives a glimpse at how to do it. I cut the real world processing time in half to less than 40ms which is a huge improvement w/ just a small tweak to the code. This can't be detected when evaluating against the local tests. Check out the video:
https://www.youtube.com/watch?v=pDwRC3KS5uwTyphonJS
YouTube
TRL Dev Snapshot (0.3.0-next.3)
This video goes over finishing your work and performance tuning. You can stop early when you have the data that you need to generate, but really digging in sometimes there are subtle performance concerns. For Foundry v13 TRL reverses the complexity of the core styles by flattening and setting the TRL CSS variables from the convoluted core styles...
@FVTT ▹ Developer The latest first actual beta for TRL Foundry v13 support is out. It includes a lot of fine tuning for v13 and the
#runtime library should be feature complete.
As things go Foundry v13 caused significant turmoil w/ all of the changes and TRL 0.3.0 is only for Foundry v13+. If you happened to be able to do a dual release w/ the last 0.3.0-next.2 release for v12/v13 that likely won't work anymore.
The #standard library components are entering beta territory and some of the dynamic styles updates are pending to exactly match Foundry core for light / dark theming. Nothing is broken, but some of that theming work remains. There are significant improvements over 0.3.0-next.2 though which was an early alpha stopgap release.
The important aspect of the beta next series is that you absolutely should do a package release of the final 0.3.0 when it is available. If you do a package release now w/ the #standard lib and don't do a release w/ the final you'll possibly be that package that loads the dynamic style management code twice. The dynamic styles uses semver and you'll see the version at the tail of <head> #standard is on 0.0.1 and it will be bumped to 0.1.0 with the final 0.3.0 release of TRL. So, all I ask is that if you make a package release now is that you do one when the final 0.3.0 TRL release is out as well. Not a problem per se as if a higher semver (alpha ordering of package loading) is before an older one... well it's semver so the higher number wins!
@typhonjs-fvtt/runtime at 0.3.0-next.3
@typhonjs-fvtt/standard at 0.3.0-next.3
Many improvements that I'll clarify over the next two weeks and upgrade essential-svelte-esm with more demos; some general highlights
- Container queries enabled out of the box. Super easy to use and very powerful w/ automatic constraints for the app window frame and content area.
- Proper SVG handling in TJSMediaContent and you can now set headerIcon to a SVG file asset.
- If you asked for a feature and we discussed it then it's available.
- All TypeScript demo repos are now updated and the types work w/ the latest PF2E / League variations.
- API docs updated.
- Again lots more, but this is not the final release notes for 0.3.0
If you have any problems please speak up. If you have any other concerns or think a particular feature should be added then get in contact.0.3.0 seems introduces styles for class .application? This messes with my styles. For example: All (but not only) h3 getting a new style applied
Heh heh.. Let me introduce you to the core v13 style rabbit hole. Down it goes and it doesn't get prettier.. For AppV2 the main app CSS class is
.application as defined by core. The app shells of TRL use .application now, so some sort of conflict w/ whatever you had setup and core, but not TRL. Even though TRL runs on top of AppV1 the app shells use the AppV2 styles to fit in w/ the platform. You wouldn't know from outward appearance that you are not using AppV2 really from SvelteApp with how it looks and behaves. There is no magic or benefit to AppV2 for TRL, but TRL utilizes the AppV2 styles.Will they not discontinue AppV1 though?
At v16 like ~1.5 years from now. I plan to introduce a much better and quite streamlined app API. Also one that will work well beyond Foundry.
Lots of good progress and I plan to make an update video soon. For those devs following progress for
0.3.0 I have a question. I'm considering adding a new SvelteApp option. Simply theme which will control any explicit theme set instead of adding the appropriate CSS classes like theme-dark to the classes option . The values for the new theme option right now are of course dark or light. If you don't explicitly set a theme then current core / platform theme is applied. SvelteApp.reactive will have new stores and accessors for the explicit app theme option.
Where this is all leading is that I'd like to make an additional activeClasses store in SvelteApp.reactive that is a reactive Set (homegrown / Svelte 4 for now / Svelte 5 has one built-in). You'll be able to add / delete classes and have the app shell update CSS classes automatically and also apply any explicit theme set or things will fallback to the current platform theme set.
I have an advanced demo / the Better Macros Directory module that has a tricky use case that benefits from more explicit control over theming and changing the theme dynamically. Normally it will have the core light / dark theme applied and uses ApplicationShell, but can switch to a transparent mode. When in the transparent mode the dark theme must be explicitly set, so the text is visible (white). You'll see at the end of quick snapshot video below an example of the transparent mode when the platform theme is light instead of dark.
------
I just want to get feedback on the new SvelteApp option for theme. In the future if Foundry provides a queryable API for additional theme installations that will be supported as well. Also it wouldn't hurt to get any feedback on the activeClasses reactive Set. I think this will be handy for dynamically adding / removing CSS classes to the app shell.It would be nice, I keep forgetting how those classes are called anyway
(If they work at all, since the selectors are bizzare)
Yeah.. With core Foundry / AppV2 you have to explicitly add
themed & theme-dark or theme-light for explicit theming. In 0.3.0-next.3 you just have to add theme-dark or theme-light to classes which is "fine", but not something that can be controlled dynamically.
I think it'll just be way easier having a theme option with just the name of the theme if an explicit theme is requested and behind the scene TRL / ApplicationShell will do the right thing in regard to what Foundry expects.
A reason to bring this up to is that this would be a change that folks currently setting an explicit theme for their packages via 0.3.0-next.3 will have to update.
I'm getting real close w/ 0.3.0-next.4. Beyond just rounding out the runtime dynamic styles / CSS layer I spent a good chunk of time in the last month adding additional reactive features that make hard things much easier for v13 and elsewhere. While I'll be making a video for the next beta release some of the neat new reactive features include:
- app.reactive.activeClasses which is a reactive Set of just the classes you provide in SvelteApp.Options making it super easy to dynamically add / delete CSS classes to main app window element at runtime.
- SvelteApp.Options.themeName - you just need to provide themeName as either dark or light to provide an explicit theme override for a particular app. There are also reactive API for changing the explicit app theme dynamically via app.reactive.themeName and a store via app.reactive.storeAppOptions.themeName.
---
One of the final technical ecosystem challenges of the new and more robust runtime dynamic styles came up as an extended ecosystem issue. As things go The Forge serves 3rd party package CSS from a separate domain / cached. The new system / module extended parsing caused CORS / SecurityException issues for The Forge. I'm working with the Forge team to relax the CORS aspects in this matter allowing cross-domain CSS access and also further hardening TRL if / when CORS does come into play and making the dynamic styles aspects gracefully fail w/ clear warning. 0.3.0-next.3 will crash / not work on The Forge as things go.
None of this is a problem when running a local server or a same origin deployment in the cloud.. Just services like the Forge. So, this means I'll also be reaching out to other cloud providers like Molten and any others as well.
This is the last general delay to getting to a final 0.3.0 release. 0.3.0-next.4 should be the last beta release w/ API / new feature introduction. There will be a 0.3.0-next.5 which will be the RC w/ final dynamic styles / all components thoroughly supporting / matching the Foundry platform. With next.5 I really want folks to make a best effort to upgrade and get ready for the final 0.3.0 release.
There were a lot of complications w/ the v13 Foundry platform changes, but solutions are in place and I think everyone will really like the TRL / theming integration that is transparent and quite powerful. You can do a lot of reactive / nice things that otherwise would be really challenging w/ the core API.
So.. I should have things hardened for The Forge and get 0.3.0.next.4 out tomorrow / Wed; heh... I guess later today. ;P
Interestingly enough the problem stylesheet was an extra one injected by The Forge, but overall this section of code that finds the main Foundry / packages stylesheets has been further hardened such that if there is a CORS failure for the core or package stylesheets a warning is logged, but things continue to work.