{"id":18016621,"url":"https://github.com/karurochori/vs-fltk","last_synced_at":"2025-08-17T20:32:22.391Z","repository":{"id":258026745,"uuid":"873243116","full_name":"KaruroChori/vs-fltk","owner":"KaruroChori","description":"Lightweight UI framework powered by fltk \u0026 scripting via tcc, quickjs, lua \u0026 wamr.","archived":false,"fork":false,"pushed_at":"2024-12-12T20:18:03.000Z","size":675,"stargazers_count":2,"open_issues_count":26,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-12T21:22:02.713Z","etag":null,"topics":["fltk","lua","quickjs","single-file-component","tinycc","ui-toolkit","wasm"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KaruroChori.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-15T20:48:39.000Z","updated_at":"2024-12-12T20:18:09.000Z","dependencies_parsed_at":"2024-11-12T11:23:45.002Z","dependency_job_id":"2cb40007-d2e3-49d4-b087-7cf6b689fef9","html_url":"https://github.com/KaruroChori/vs-fltk","commit_stats":null,"previous_names":["karurochori/vs-fltk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaruroChori%2Fvs-fltk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaruroChori%2Fvs-fltk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaruroChori%2Fvs-fltk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaruroChori%2Fvs-fltk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KaruroChori","download_url":"https://codeload.github.com/KaruroChori/vs-fltk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230167800,"owners_count":18183845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fltk","lua","quickjs","single-file-component","tinycc","ui-toolkit","wasm"],"created_at":"2024-10-30T04:18:40.509Z","updated_at":"2025-08-17T20:32:22.374Z","avatar_url":"https://github.com/KaruroChori.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./commons/assets/logos/vs.dark.svg#gh-dark-mode-only\" alt=\"Fancy logo\" width=\"250\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./commons/assets/logos/vs.light.svg#gh-light-mode-only\" alt=\"Fancy logo\" width=\"250\"\u003e\n\u003c/p\u003e\n\n\u003e [!IMPORTANT]  \n\u003e This project is very much in its infancy.  \n\u003e This README is half features in a workable state, and half wishful thinking.  \n\u003e This holds true for rest of the docs as well.\n\n\u003e [!WARNING]  \n\u003e Safety \u0026 Security policies have not been implemented or fully tested yet.\n\u003e Running untrusted XML files on VS can lead to [arbitrary code execution](./docs/users/safety-policies.md) on your machine with your user privileges.\n\nHey, you there! Yes you! May I entertain you with something slightly cursed?  \nHave you ever woken up in the middle of the night, thinking:\n\n\u003e \"Maaan, I'd really love to put a pinch of C, JS and WASM into my XML files and get a UI with vibes out of the 90's for my fancy codebase\".\n\nWell, you should eat lighter before nighttime.  \nStill, it is your lucky day, \u0026 this project might be for you!\n\n[![Building-Testing-badge]][Building-Testing-url]\n\n## What is VS (naming review pending)\n\nVS is a front-end framework based on the concept of composable SFCs (Single File Components).  \nMore specifically, VS is a runtime with very low resource requirements, that takes a dependency tree of XML SFCs, and renders it using a portable native toolkit library into a lightweight UI.  \nLayout, style, data handling and embedded scripts are all part of these reusable components. They are embedded in the XML file pretty much as you would do with HTML.\n\nVS is based on [FLTK](https://www.fltk.org/), a very lightweight and portable UI toolkit.  \nComparing its memory footprint with GTK or QT is not even fun.\n\n## Example\n\nThe obligatory \"counter\" [example](./examples/demo-c.xml):  \n![demo image](./docs/assets/demo.png)\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003capp xmlns:fl=\"vs.fltk\"\u003e\n    \u003cfl:window box=\"0,0,320,240\" label=\"Demo Counter\"\u003e\n        \u003cmixin name=\"+fl:button\" bg.colour=\"#aa3300\" label.colour=\"#99ee4f\" /\u003e\n        \u003cscript lang=\"c\"\u003e\n        \u003c![CDATA[\n        unsigned int counter = 0;\n\n        void _update(){\n            static char str_buf[32];\n            itoa(counter,str_buf,10);\n            $$prop($(\"main-text\"),\"label\",str_buf);\n        }\n\n        void on_add(){\n            counter++;\n            _update();\n        }\n\n        void on_dec(){\n            counter--;\n            _update();\n        }\n\n        $cb(on_add);\n        $cb(on_dec);\n        ]]\u003e\n        \u003c/script\u003e\n\n        \u003cfl:label name=\"main-text\" label=\"0\" label.size=\"90\" box=\"20,20,280,120\" /\u003e\n        \u003cfl:button label=\"Add\" on.callback=\"on_add\" box=\"20,160,80,50\" /\u003e\n        \u003cfl:button label=\"Remove\" on.callback=\"on_dec\" box=\"120,160,80,50\" /\u003e\n        \u003cfl:button label=\"Console\" box=\"220,160,80,50\"\u003e\n            \u003cscript lang=\"c\"\u003e\n            \u003c![CDATA[\n            void callback(){\n                $log(LOG_LOG,\"Hello world!\");\n            }\n            ]]\u003e\n            \u003c/script\u003e\n        \u003c/fl:button\u003e\n    \u003c/fl:window\u003e\n\u003c/app\u003e\n```\n\nThere is also a [js version](./examples/demo-js.xml) for reference.\n\n## Why?\n\nBecause the current landscape of UI development kind of stinks. And to be totally honest, a lot of that smell comes from web technologies.  \nWe constructed layers over layers of complexity to wrap and bend HTML, to the point that its native UI components are not even used.  \nAnd now we are required to waste at least 100MB of RAM just for the privilege of running webkit with an empty page.\n\nIt is sad to see that most of the modern native toolkits followed this same trend: QT \u0026 GTK both became a bloated mess over the last few years.  \nFor many desktop applications, any UI is just an overlay to give easy and intuitive access to the complex application below. And to make features discoverable. We don't need transparency, animations or a super complex logic to determine the state of a widget.  \nAnd oftentimes, we want to run them on very low spec Linux system, without resorting to something as bare bone as [lvgl](https://lvgl.io/).\n\n`vs` is an attempt to bring together the best of the techniques and patterns we learned in modern UI frameworks \u0026 web technologies onto a native runtime with a miniscule footprint.\n\nCompared to other approaches, `vs` is extremely opinionated and tries to enforce just one way to make things right. It does not mean it is inflexible, just that it makes clear where complexity should be (spoiler, not in the UI). If you are coming from a less restrictive context you might find these limitations unpleasant at first, so I compiled a list of [frequently asked questions](./docs/faq.md) no one asked for, to make things easier.\n\n## Planned Features\n\n- [ ] FLTK UI widgets properly mapped into XML.\n  - [ ] A set of better themes as default\n  - [ ] A markdown component to render it directly (replacing the ancient HTML2.0 webview FLTK offers)\n- [ ] A simple tree model to handle scope, events and queries\n- [ ] An XML templating solution, baically a preprocessor like XSLT to compile _templates + static data_ down to components directly on client\n- [ ] Native support for datasets \u0026 data models and their presentation layer\n- [ ] Custom (application specific \u0026 sharable) components\n  - [ ] XML custom components, capable of embedding any other type\n  - [ ] Markdown-based custom components, capable of embedding `vs` code in place of HTML. Good for documentation\n  - [ ] Native custom components, externally compiled from any language\n  - [ ] WASM custom components, externally compiled from any language\n  - [ ] A compiler to transform XML components directly into native code, so that they can run on natively, on WASM or in the riscv vm\n- [ ] Embedded code inside XML components (like JS in HTML)\n  - [ ] C as a scripting language, backed by [tinycc](https://github.com/KaruroChori/tcc-vs).\n  - [ ] ~~Other derived alternatives, like [cello](https://libcello.org) or [vala](https://vala.dev/) would also be possible~~\n  - [ ] JS powered by [QuickJS](https://github.com/quickjs-ng).\n  - [ ] Lua, either based on its reference implementation or LuaJIT.\n  - [ ] WASM to run any language which can be compiled to this target \u0026 their compilers\n  - [ ] A RISCV virtual machine to run components from any language supporting this architecture\n- [ ] Interoperability with external code:\n  - [ ] Native interoperability with external dynamic libraries\n  - [ ] Interoperability with arbitrary services/processes via unix domain sockets\n- [ ] Distribution of components via http/https and [gemini](https://geminiprotocol.net/)\n- [ ] A self-hosted visual editor to design, code and test new components (something like [gambas](https://gambas.sourceforge.net/en/main.html) or [fluid](https://www.fltk.org/doc-1.4/fluid.html))\n- [ ] A robust permission system to decide what components can do based on their origin\n- [ ] A target for single executables; compile your app down into one sharable file for systems onto which `vs` is not already distributed\n\nYou can read more about which features are planned in the [milestones page](./MILESTONES.md).\n\n## Useful documentation\n\n- Instuctions [for developers](./docs/developers/index.md)\n- Instuctions (not yet) [for users](./docs/users/index.md) of vs\n- Complete (not yet) [specifications](./docs/full-specs/index.md) for `vs`\n\n## Licences\n\n`vs` is copyrighted by [karurochari](https://github.com/KaruroChori) \u0026 [other contributors](https://github.com/KaruroChori/vs-fltk/graphs/contributors).  \nPlease, check the git history to track authorship.\n\nCurrently, most of this project is _source available_, under the terms of CC BY-ND. You can find out more in the [FAQ](./docs/faq.md).  \nStill, any derivative work for private use, or for the sake of merging functionalities back to the main repository is allowed and encouraged.  \nI am taking PR, but contributors should understand that the project is very early, and changes in its direction might waste their time.  \nThey should also be ok with their code being relicensed under more permissive terms later on, as this is the general intent behind the project once stable enough.\n\nStill, some part of this repo are licenced separately:\n\n- All `bindings` are CC0\n- `examples` and `docs` are CC BY-SA\n- Each of the subprojects imported clearly keeps its own licence and copyright notice.\n\nUnless a file comes with a custom licence in its header, it will inherit the one of the closest parent folder.\n\n## Dependencies\n\nThis project is based on the following dependencies:\n\n### Core features\n\n- [fltk](https://www.fltk.org/) the UI toolkit library used.\n- [vs.templ](https://github.com/lazy-eggplant/vs.templ) a template engine for XML.\n- [vs.yapm](https://github.com/lazy-eggplant/vs.yapm) yet another packet manager.\n- [vs.xml-piler](https://github.com/lazy-eggplant/vs.xml-piler) to generate the XML parser backends based on schema files and specs.\n\n### Infrastructure\n\n- [pugixml](https://pugixml.org/) to parse XML.\n- [sqlite](https://www.sqlite.org/) as the embedded DB to handle user profiles, caching etc.\n- [mio](https://github.com/vimpunk/mio) memory mapping for loading files.\n- [hashlib](https://github.com/lazy-eggplant/hash-library) for cryptographic functions (and not).\n- [libuv](https://libuv.org/) for me not to care about portable code.\n- [libffi](https://github.com/libffi/libffi) to simplify symbol sharing between languages.\n- [libsodium](https://doc.libsodium.org/) for crypto stuff.\n\n### For embedded scripts\n\n- [tcc](https://github.com/lazy-eggplant/tcc-vs) the embeddable C compiler used for C scripts.\n- [quickjs](https://github.com/quickjs-ng) the embeddable JS runtime used for JS scripts.\n- [lua](https://www.lua.org/) and [luajit](http://luajit.org/) to support Lua scripts.\n- [libriscv](https://github.com/libriscv/libriscv) the embeddable RISCV virtual machine, used for scripts, portable compiled components \u0026 toolchains.\n- [wamr](https://github.com/bytecodealliance/wasm-micro-runtime) the embeddable WASM runtime used for scripts, portable compiled components \u0026 toolchains.\n\n### For custom components\n\n- [treesitter](https://tree-sitter.github.io/tree-sitter/) to handle parsing of languages (used for some components and the self-hosted editor).\n- [md4c](https://github.com/mity/md4c) a library to parse markdown (not just to HTML).\n- [nlohmann-json](https://github.com/nlohmann/json) to parse JSON in some `data` directives\n- [vs.robot](https://github.com/lazy-eggplant/vs.robot) a library to perform automatic actions on FLTK.\n\n[Building-Testing-badge]: https://github.com/KaruroChori/vs-fltk/actions/workflows/build.yml/badge.svg?branch=master\n[Building-Testing-url]: https://github.com/KaruroChori/vs-fltk/actions/workflows/build.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarurochori%2Fvs-fltk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarurochori%2Fvs-fltk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarurochori%2Fvs-fltk/lists"}