syntropy 0.15.1 → 0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef2840797122cef8e0f7f7675c10665c35f60915e091043416ffd0ed70e1cb5c
-  data.tar.gz: 0d929bfbe0d629879b05c57b7c01c1e8c0ee1af148dc23570c30233f19e81156
+  metadata.gz: b90967d51ee11dd83db1237db95b35fb1a2bd9cb36248086bfe62082ddd4c0a5
+  data.tar.gz: 187eb2adc5a21df0f8d0400ef54609300658df9e3ba371686c1007d4744c0667
 SHA512:
-  metadata.gz: 6375f3fb5cbab65d6b710b613c32d0eb9ebb714880f0eb3921fd0b07da9219e0ab94faec2398ae2f33a21fa4f21a8135416faf5b6f2ad0721a99afa067b854f7
-  data.tar.gz: 715274f642dc3b0db72b0ec37526f26221b56930e19eb324f804408b18552a5c465d59f313cd8329a24a9caa0aa05abaa6907d523f15e1e7061e3e9e1bf1762c
+  metadata.gz: 1c0aff28315990526db9d48c1d4dba164d9944f93bdbcb671fdd6526a2f77eac28fa89cc2a99e68ce6bc5e55db85582270b3ea6032456c5e5d2fe9847150e3ae
+  data.tar.gz: 10d5ceb7568d22a07d89e13cca104aeeeea94e62a03c778a72c3da360b8a21ef466038d4d872b75ae00b1634c2dfffc8931e4a61695e95e99c78a51bfcd5c643

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 0.16 2025-09-11
+
+- `syntropy` script:
+  - Remove trailing slash for root dir in syntropy script
+  - Rename `-w/--watch` option to `-d/--dev` for development mode
+  - Fix `--mount` option
+- Add builtin `/.syntropy` applet for builtin features:
+  - auto refresh for web pages
+  - JSON API
+  - Template debugging frontend tools
+  - ping route
+  - home page with links to examples
+- Implement applet mounting and loading
+- Remove Papercraft dependency
+- Add support for P2 XML templates, using `#template_xml`
+- Update P2, TP2
+
 # 0.15 2025-08-31
 
 - Implement invalidation of reverse dependencies on module file change

data/TODO.md

@@ -22,6 +22,8 @@
   article.layout #=>
   article.render_proc #=> (load layout, apply article)
   article.render #=> (render to HTML)
+
+  # there should also be methods for creating, updating and deleting of articles/items.
   ...
   ```
 
@@ -30,6 +32,149 @@
   - [ ] support for caching headers
   - [ ] add `Request#render_static_file(route, fn)
 
+- [ ] Serving of built-in assets (mostly JS)
+  - [ ] JS lib for RPC API
+
+## Missing for a first public release
+
+- [ ] Logo
+- [ ] Website
+- [ ] Frontend part of RPC API
+- [v] Auto-refresh page when file changes
+- [ ] Examples
+  - [ ] Reactive app - counter or some other simple app showing interaction with server
+  - [ ] ?
+
+## Counter example
+
+Here's a react component (from https://fresh.deno.dev/):
+
+```jsx
+// islands/Counter.tsx
+import { useSignal } from "@preact/signals";
+
+export default function Counter(props) {
+  const count = useSignal(props.start);
+
+  return (
+    <div>
+      <h3>Interactive island</h3>
+      <p>The server supplied the initial value of {props.start}.</p>
+      <div>
+        <button onClick={() => count.value -= 1}>-</button>
+        <div>{count}</div>
+        <button onClick={() => count.value += 1}>+</button>
+      </div>
+    </div>
+  );
+}
+```
+
+How do we do this with Syntropy? Can we make a component that does the
+templating and the reactivity in a single file? Can we wrap reactivity in a
+component that has its own state? And where does the state live?
+
+```ruby
+class Counter < Syntropy::Component
+  def initialize(start:, **props)
+    @count = reactive()
+  end
+
+  def template
+    div {
+      h3 'Interactive island'
+      p "The server supplied the initial value of #props[:start]}"
+      div {
+        button '-', on_click: -> { @count.value -= 1 }
+        div @count.value
+        button '+', on_click: -> { @count.value += 1 }
+      }
+    }
+  end
+end
+```
+
+Hmm, don't know if the complexity is worth it. It's an abstraction that's very
+costly - both in terms of complexity of computation, and in terms of having a
+clear mental model of what's happening under the hood.
+
+I think a more logical approach is to stay with well-defined boundaries between
+computation on the frontend and computation on the backend, and a having a clear
+understanding of where things happen:
+
+```ruby
+class Counter < Syntropy::Component
+  def incr
+    update(value: @props[:value] + 1)
+  end
+
+  def decr
+    update(value: @props[:value] - 1)
+  end
+
+  def template
+    div {
+      h3 'Interactive island'
+      div {
+        button '-', syn_click: 'decr'
+        div @props[:value]
+        button '+', syn_click: 'incr'
+      }
+    }
+  end
+end
+```
+
+Now, we can do all kinds of wrapping with scripts and ids and stuff to make this
+work, but still, it would be preferable for the interactivity to be expressed in
+JS. Maybe we just need a way to include a script that acts on the local HTML
+code. How can we do this without writing a web component etc?
+
+One way is to assign a random id to the template, then have a script that works
+on it locally.
+
+```ruby
+export template { |**props|
+  id = SecureRandom.hex(4)
+  div(id: id) {
+    h3 'Interactive island'
+    div {
+      button '-', syn_action: "decr"
+      div props[:value], syn_value: "value"
+      button '+', syn_action: "incr"
+    }
+    script <<~JS
+      const state = { value: #{props[:value]} }
+      const root = document.querySelector('##{id}')
+      const decr = root.querySelector('[syn-action="decr"]')
+      const incr = root.querySelector('[syn-action="incr"]')
+      const value = root.querySelector('[syn-value="value"]')
+      const updateValue = (v) => { state.value = v; value.innerText = String(v) }
+
+      decr.addEventListener('click', (e) => { updateValue(state.value - 1) })
+      incr.addEventListener('click', (e) => { updateValue(state.value + 1) })
+    JS
+  }
+}
+```
+
+How can we make this less verbose, less painful, less error-prone?
+
+One way is to say - we don't worry about this on the backend, we just write
+normal JS for the frontend and forget about the whole thing. Another way is to
+provide a set of tools for making this less painful:
+
+- Add some fancier abstractions on top of the JS RPC lib
+- Add some template extensions that inject JS into the generated HTML
+
+## Testing facilities
+
+- What do we need to test?
+  - Routes
+  - Route responses
+  - Changes to state / DB
+  -
+
 ## Support for applets
 
 - can be implemented as separate gems

data/bin/syntropy

@@ -7,7 +7,8 @@ require 'optparse'
 env = {
   mount_path: '/',
   banner: Syntropy::BANNER,
-  logger: true
+  logger: true,
+  builtin_applet_path: '/.syntropy'
 }
 
 parser = OptionParser.new do |o|
@@ -24,7 +25,8 @@ parser = OptionParser.new do |o|
     env[:logger] = nil
   end
 
-  o.on('-w', '--watch', 'Watch for changed files') do
+  o.on('-d', '--dev', 'Development mode') do
+    env[:dev_mode] = true
     env[:watch_files] = 0.1
   end
 
@@ -33,8 +35,14 @@ parser = OptionParser.new do |o|
     exit
   end
 
-  o.on('-m', '--mount', 'Set mount path (default: /)') do
-    env[:mount_path] = it
+  o.on('-m', '--mount PATH', 'Set mount path (default: /)') do |path|
+    p mount: path
+    env[:mount_path] = path
+    env[:builtin_applet_path] = File.join(path, '.syntropy')
+  end
+
+  o.on('--no-builtin-applet', 'Do not mount builtin applet') do
+    env[:builtin_applet_path] = nil
   end
 
   o.on('-v', '--version', 'Show version') do
@@ -54,7 +62,7 @@ rescue StandardError => e
   exit
 end
 
-env[:root_dir] = ARGV.shift || '.'
+env[:root_dir] = (ARGV.shift || '.').gsub(/\/$/, '')
 
 if !File.directory?(env[:root_dir])
   puts "#{File.expand_path(env[:root_dir])} Not a directory"
@@ -70,6 +78,7 @@ env[:machine] = Syntropy.machine = UM.new
 env[:logger] = env[:logger] && TP2::Logger.new(env[:machine], **env)
 
 require 'syntropy/version'
+require 'syntropy/dev_mode' if env[:dev_mode]
 
 env[:logger]&.info(message: "Running Syntropy version #{Syntropy::VERSION}")
 app = Syntropy::App.load(env)

data/examples/card.rb

@@ -0,0 +1,12 @@
+export template {
+  card {
+    h2 'Some card'
+    h3 'Some subtitle'
+
+    markdown <<~MARKDOWN
+      - Foo
+      - Bar
+      - Baz
+    MARKDOWN
+  }
+}

data/examples/counter.js

@@ -0,0 +1,20 @@
+import JSONAPI from '/.syntropy/json_api.js'
+
+(() => {
+  const api = new JSONAPI('/counter_api');
+
+  const value = document.querySelector('#value');
+  const decr  = document.querySelector('#decr');
+  const incr  = document.querySelector('#incr');
+
+  decr.addEventListener('click', async () => {
+    const result = await api.post('decr')
+    value.innerText = String(result);
+  });
+
+  incr.addEventListener('click', async () => {
+    const result = await api.post('incr')
+    value.innerText = String(result);
+  });
+
+})()

data/examples/counter.rb

@@ -0,0 +1,23 @@
+CounterAPI = import 'counter_api'
+
+export template {
+  html5 {
+    body {
+      p { a '< Home', href: '/' }
+
+      h1 'Counter'
+
+      div {
+        button '-', id: 'decr'
+        value CounterAPI.value, id: 'value'
+        button '+', id: 'incr'
+      }
+    }
+    script src: '/counter.js', type: 'module'
+    style <<~CSS
+      div { font-weight: bold; font-size: 1.3em }
+      value { display: inline-block; padding: 0 1em; color: blue; width: 1em }
+    CSS
+    auto_refresh_watch!
+  }
+}

data/examples/counter_api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CounterAPI < Syntropy::JSONAPI
+  def initialize(env)
+    @env = env
+    @value = env[:counter_value] || 0
+  end
+
+  def value(req = nil)
+    @value
+  end
+
+  def incr!(req)
+    @value += 1
+  end
+
+  def decr!(req)
+    @value -= 1
+  end
+end
+
+export CounterAPI

data/examples/index.md

@@ -0,0 +1,8 @@
+---
+title: Syntropy Examples
+---
+
+# Syntropy Examples
+
+- [Template composition](/templates)
+- [JSON API](/counter)

data/examples/templates.rb

@@ -0,0 +1,40 @@
+Card = import 'card'
+
+export template {
+  html5 {
+    head {
+      style {
+        raw <<~CSS
+          div {
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+          }
+          span.foo {
+            color: white;
+            background-color: blue;
+            padding: 1em;
+          }
+          span.bar {
+            color: white;
+            background-color: green;
+            padding: 1em;
+          }
+        CSS
+      }
+    }
+    body {
+      p { a '< Home', href: '/' }
+
+      h1 'Testing'
+
+      div {
+        span 'foo', class: 'foo'
+        span 'bar', class: 'bar'
+      }
+
+      Card()
+    }
+    auto_refresh_watch!
+    debug_template!
+  }
+}

data/lib/syntropy/app.rb

@@ -43,6 +43,7 @@ module Syntropy
       @root_dir = File.expand_path(env[:root_dir])
       @mount_path = env[:mount_path]
       @env = env
+      @logger = env[:logger]
 
       @module_loader = Syntropy::ModuleLoader.new(app: self, **env)
       setup_routing_tree
@@ -70,15 +71,22 @@ module Syntropy
       proc = route[:proc] ||= compute_route_proc(route)
       proc.(req)
     rescue StandardError => e
-      @env[:logger]&.error(
-        message: "Error while serving request",
+      @logger&.error(
+        message: "Error while serving request: #{e.message}",
         method: req.method,
-        path: req.path
+        path: req.path,
+        error: e
       )
       error_handler = get_error_handler(route)
       error_handler.(req, e)
     end
 
+    def route(path, params = {}, compute_proc: false)
+      route = @router_proc.(path, params)
+      route[:proc] ||= compute_route_proc(route) if compute_proc
+      route
+    end
+
     private
 
     # Instantiates a routing tree with the app settings, and generates a router
@@ -89,9 +97,16 @@ module Syntropy
       @routing_tree = Syntropy::RoutingTree.new(
         root_dir: @root_dir, mount_path: @mount_path, **@env
       )
+      mount_builtin_applet if @env[:builtin_applet_path]
       @router_proc = @routing_tree.router_proc
     end
 
+    def mount_builtin_applet
+      path = @env[:builtin_applet_path]
+      @builtin_applet ||= Syntropy.builtin_applet(@env, mount_path: path)
+      @routing_tree.mount_applet(path, @builtin_applet)
+    end
+
     # Computes the route proc for the given route, wrapping it in hooks found up
     # the routing tree.
     #
@@ -146,9 +161,9 @@ module Syntropy
       if (layout = atts[:layout])
         route[:applied_layouts] ||= {}
         proc = route[:applied_layouts][layout] ||= markdown_layout_proc(layout)
-        html = proc.render(md: md, **atts)
+        html = proc.render(md:, **atts)
       else
-        html = P2.markdown(md)
+        html = default_markdown_layout_proc.render(md:, **atts)
       end
       html
     end
@@ -160,9 +175,22 @@ module Syntropy
       @layouts[layout] = template.apply { |md:, **| markdown(md) }
     end
 
+    def default_markdown_layout_proc
+      @default_markdown_layout ||= ->(md:, **atts) {
+        html5 {
+          head {
+            title atts[:title]
+          }
+          body {
+            markdown md
+            auto_refresh_watch!
+          }
+        }
+      }
+    end
+
     def module_route_proc(route)
       ref = @routing_tree.fn_to_rel_path(route[:target][:fn])
-      # ref = route[:target][:fn].sub(@mount_path, '')
       mod = @module_loader.load(ref)
       compute_module_proc(mod)
     end
@@ -171,31 +199,23 @@ module Syntropy
       case mod
       when P2::Template
         p2_template_proc(mod)
-      when Papercraft::Template
-        papercraft_template_proc(mod)
       else
         mod
       end
     end
 
     def p2_template_proc(template)
+      xml_mode = template.mode == :xml
       template = template.proc
-      headers = { 'Content-Type' => 'text/html' }
+      mime_type = xml_mode ? 'text/xml; charset=UTF-8' : 'text/html; charset=UTF-8'
+      headers = { 'Content-Type' => mime_type }
 
-      ->(req) {
-        req.respond_by_http_method(
-          'head'  => [nil, headers],
-          'get'   => -> { [template.render, headers] }
-        )
-      }
-    end
+      get_proc = xml_mode ? -> { [template.render_xml, headers] } : -> { [template.render, headers] }
 
-    def papercraft_template_proc(template)
-        headers = { 'Content-Type' => template.mime_type }
       ->(req) {
         req.respond_by_http_method(
           'head'  => [nil, headers],
-          'get'   => -> { [template.render, headers] }
+          'get'   => get_proc
         )
       }
     end
@@ -232,7 +252,7 @@ module Syntropy
     DEFAULT_ERROR_HANDLER = ->(req, err) {
       msg = err.message
       msg = nil if msg.empty? || (req.method == 'head')
-      req.respond(msg, ':status' => Syntropy::Error.http_status(err))
+      req.respond(msg, ':status' => Syntropy::Error.http_status(err)) rescue nil
     }
 
     # Returns an error handler for the given route. If route is nil, looks up
@@ -286,7 +306,7 @@ module Syntropy
         # setup tasks
         @machine.sleep 0.2
         route_count = @routing_tree.static_map.size + @routing_tree.dynamic_map.size
-        @env[:logger]&.info(
+        @logger&.info(
           message: "Serving from #{@root_dir} (#{route_count} routes found)"
         )
 
@@ -302,7 +322,7 @@ module Syntropy
       wf = @env[:watch_files]
       period = wf.is_a?(Numeric) ? wf : 0.1
       Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
-        @env[:logger]&.info(message: "File change detected", fn: fn)
+        @logger&.info(message: 'File change detected', fn: fn)
         @module_loader.invalidate_fn(fn)
         debounce_file_change
       end
@@ -324,7 +344,23 @@ module Syntropy
         @machine.sleep(0.1)
         setup_routing_tree
         @routing_tree_reloader = nil
+        signal_auto_refresh_watchers!
       end
     end
+
+    def signal_auto_refresh_watchers!
+      return if !@builtin_applet
+
+      watcher_route_path = File.join(@env[:builtin_applet_path], 'auto_refresh/watch.sse')
+      watcher_route = @builtin_applet.route(watcher_route_path, compute_proc: true)
+
+      watcher_mod = watcher_route[:proc]
+      watcher_mod.signal!
+    rescue => e
+      @logger&.error(
+        message: 'Unexpected error while signalling auto refresh watcher',
+        error: e
+      )
+    end
   end
 end

data/lib/syntropy/applets/builtin/auto_refresh/watch.js

@@ -0,0 +1,12 @@
+(() => {
+  const jsURL = import.meta.url;
+  const sseURL = jsURL.replace(/\.js$/, '.sse');
+  const eventSource = new EventSource(sseURL);
+
+  eventSource.addEventListener('message', (msg) => {
+    if (msg.data != '') window.location.reload();
+  })
+  eventSource.addEventListener('error', () => {
+    console.log(`Failed to connect to auto refresh watcher (${sseURL})`);
+  })
+})()

data/lib/syntropy/applets/builtin/auto_refresh/watch.sse.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# This module implements an SSE (server-sent events) route, that emits a message
+# to the client when a file has been changed. The module is signalled by the
+# running app whenever a file change, when in watch mode (`-w`). This route
+# resides by default at `/.syntropy/auto_refresh/watch.sse`.
+#
+# The complementary client-side party is implemented in a small JS script
+# residing by default at `/.syntropy/auto_refresh/watch.js`.
+
+# Returns a hash holding references to queues for ongoing `watch.sse` requests.
+def watchers
+  @watchers ||= {}
+end
+
+# Signals a file change by pushing to all watcher queues.
+def signal!
+  watchers.each_key { @machine.push(it, true) }
+end
+
+# Handles incoming requests to the `watch.sse` route. Adds a queue to the list
+# of watchers, and waits for the queue to be signalled. In the absence of file
+# change, a timeout occurs after one minute, and the request is terminated.
+def call(req)
+  queue = UM::Queue.new
+  watchers[queue] = true
+
+  req.send_headers('Content-Type' => 'text/event-stream')
+  req.send_chunk("data: \n\n")
+  @machine.timeout(60, Timeout::Error) do
+    @machine.shift(queue)
+    req.send_chunk("data: refresh\n\n")
+  end
+  req.send_chunk("retry: 0\n\n", done: true) rescue nil
+rescue Timeout::Error
+  req.send_chunk("retry: 0\n\n", done: true) rescue nil
+rescue SystemCallError
+  # ignore
+rescue => e
+  @logger&.error(
+    message: 'Unexpected error encountered while serving auto refresh watcher',
+    error: e
+  )
+  req.finish rescue nil
+ensure
+  watchers.delete(queue)
+end
+
+export self

data/lib/syntropy/applets/builtin/debug/debug.css

@@ -0,0 +1,61 @@
+debug-attachment {
+  position: relative;
+  /* display: block; */
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  /* opacity: 0; */
+  width: 100%;
+  height: 100%;
+}
+
+debug-label {
+  display: block;
+  position: absolute;
+  top: -12px;
+  left: 4px;
+  background: rgba(0, 0, 0, 0.8);
+  color: white;
+  padding: 2px 6px;
+  font-size: 11px;
+  font-family: 'Segoe UI', Roboto, monospace;
+  font-weight: 500;
+  border-radius: 3px;
+  display: block;
+  z-index: 1001;
+  cursor: pointer;
+  /* transition: all 0.2s ease; */
+  white-space: nowrap;
+  line-height: 1.2;
+
+  a, a:hover, a:visited {
+    color: white;
+  }
+
+  &:hover {
+    display: block;
+  }
+
+  &.fn {
+    display: block;
+  }
+}
+
+body *:not(script)[data-syntropy-level]:hover {
+  outline: #13630c dotted 2px;
+  outline-offset: 2px;
+
+  /* debug-label {
+    display: block;
+  }   */
+}
+
+body[data-syntropy-level="1"], body *:not(script)[data-syntropy-level="1"] {
+  outline: #2357aa dotted 2px;
+  outline-offset: 2px;
+}
+
+card {
+  display: block;
+}