DatumHue — App Author's Guide

What is DatumHue

DatumHue is a creative workstation. You write apps in Lua that run inside the DatumHue client. Apps draw 2D and 3D graphics, play audio, handle input, load and visualize data, and collaborate in real time. Many apps run at once, arranged by a window manager — itself just another Lua app.

Apps can download content, exchange messages, and share live documents with other clients.

Who this guide is for

This guide is for people writing apps in DatumHue. It teaches the models and conventions behind the datumhue.* API — what an app is, how it draws, how it loads data, how it talks to other apps. It does not list every function signature — those live in the API reference alongside this guide, generated from the client you have installed so they always match your version.

You should be comfortable with Lua. No prior DatumHue knowledge is assumed.

Contents

• Specifications
• Quick start
• Core concepts
  • Apps, the process tree, and the window manager
  • The app window
  • Coordinate systems
  • Capabilities and permissions
  • The app lifecycle
  • When a callback errors
  • Suspending calls
  • Sessions
• Packages
• Working with the API
  • Drawing and 3D
  • Shaders
  • User interface
  • Theming
  • Display and input
  • Filesystem and data capabilities
  • Books and documents
  • Bytes and encoding
  • Tabular data
  • Charts
  • Storage
  • Identity
  • Messaging, events, and documents
  • HTTP
  • The package catalog
• The Lua environment
• Tooling
• Gotchas
• Glossary
• The API reference

Specifications

Quick start

An app is a Lua script. The script body runs once when the app spawns; to animate, register an update handler with datumhue.on_update(fn). Run any of the examples below with datumhue run <file>.lua.

While iterating, add --watch: every save reloads the running app. A code change relaunches it from the fresh source — a save that does not compile keeps the current version running and reports the error — and a change to an asset the app has loaded (an image, a sound, a scene) is applied in place, without a relaunch and without losing the app's state. datumhue repl accepts the same flag, and the console re-attaches across reloads.

Hello world

local color = datumhue.color

local bg = datumhue.ui.root:panel({
    width = 400, height = 300, color = color("#1a1a2e"),
})
bg:label({
    left = 120, top = 130,
    text = "Hello, DatumHue!",
    font_size = 24, color = color("#e0e0e0"),
})

A bouncing ball

A canvas is an offscreen surface; mount it with canvas:mount() so the drawing shows up on screen. Primitives persist across frames — create them once, then update their properties.

local color = datumhue.color
local vec2 = datumhue.math.vec2
local W, H, R = 320, 240, 12

local canvas = datumhue.draw.new({width = W, height = H, background = color("#1a1a2e")})
canvas:mount({width = W, height = H})

local pos = vec2(0, 0)
local vel = vec2(120, 80)
local bounds = vec2(W / 2 - R, H / 2 - R)

local ball = canvas:circle({pos = pos:extend(1), radius = R, color = color("#e94560")})

datumhue.on_update(function(dt)
    pos = pos + vel * dt
    if math.abs(pos.x) > bounds.x then vel = vel:with_x(-vel.x) end
    if math.abs(pos.y) > bounds.y then vel = vel:with_y(-vel.y) end
    ball:update({pos = pos:extend(1)})
end)

Pixel art

For retro framebuffer drawing, use the image API. You record drawing into a picture and replay it onto an image with image:apply — the whole frame lands at once, with nothing half-drawn ever visible. Build the picture once and reuse it; picture:reset() clears it for the next frame.

local color = datumhue.color
local W, H = 128, 128

local c = datumhue.image.new({width = W, height = H})
c:mount({width = W * 4, height = H * 4})  -- 4x upscale
local pic = datumhue.image.picture()

datumhue.on_update(function()
    local t = datumhue.time.now()
    pic:reset()
    pic:clear()
    local x = 64 + math.cos(t * 2) * 40
    local y = 64 + math.sin(t * 3) * 30
    pic:circfill(x, y, 8, color("#ff004d"))
    pic:print("hello", 48, 58, color("#fff1e8"))
    c:apply(pic)
end)

For animated sprites and tile maps, slice an image into a grid with image:atlas, then draw cells onto a draw canvas with canvas:sprite(atlas:sprite(index), {pos = …}) (set prim.cell to animate), or fill a canvas:tilemap(atlas, {columns = …, rows = …}) with tilemap:set(x, y, cell). Because they are real draw primitives, sprites compose with physics, shaders, and picking. Draw a whole image (or another canvas/scene) with canvas:image.

local color = datumhue.color
local vec2 = datumhue.math.vec2
local vec3 = datumhue.math.vec3

-- Paint a 4-frame strip of 16x16 cells: a dot orbiting each cell's center.
local sheet = datumhue.image.new({width = 64, height = 16})
local pic = datumhue.image.picture()
local steps = {vec2(4, 0), vec2(0, 4), vec2(-4, 0), vec2(0, -4)}
for i = 0, 3 do
    local s = steps[i + 1]
    pic:circfill(8 + i * 16 + s.x, 8 + s.y, 3, color("#ffcc00"))
end
sheet:apply(pic)

local atlas = sheet:atlas({tile_size = vec2(16, 16), columns = 4, rows = 1})

-- Draw cell 0 as a sprite, then cycle the cell to animate.
local canvas = datumhue.draw.new({width = 128, height = 128})
canvas:mount({width = 128, height = 128})
local prim = canvas:sprite(atlas:sprite(0, {size = vec2(48, 48)}), {pos = vec3(0, 0, 1)})

datumhue.on_update(function()
    prim.cell = math.floor(datumhue.time.now() * 8) % 4
end)

A 3D scene

Scenes are retained-mode — primitives persist until removed.

local color = datumhue.color
local vec3 = datumhue.math.vec3
local W, H = 800, 600

local scene = datumhue.scene.new({width = W, height = H, hdr = true})
scene:mount({width = W, height = H})

scene:cube({pos = vec3(0, 0, 0), color = color("#4488ff")})
scene:directional_light({direction = vec3(-0.5, -1, -0.2), intensity = 12000, shadows = true})
scene.camera.pos = vec3(3, 3, 3)
scene.camera:look_at(vec3(0, 0, 0))
scene.bloom = {intensity = 0.2}

Physics

local color = datumhue.color
local vec3 = datumhue.math.vec3
local W, H = 400, 400

local canvas = datumhue.draw.new({width = W, height = H, background = color("#111111")})
canvas:mount({width = W, height = H})

local box = canvas:rect({pos = vec3(-10, 100, 1), width = 20, height = 20, color = color("#ff6b6b")})
box:add_body({type = "dynamic", shape = "rect"})

local floor = canvas:rect({pos = vec3(-150, -180, 1), width = 300, height = 20, color = color("#4ecdc4")})
floor:add_body({type = "static", shape = "rect"})

All 2D physics bodies that should collide must share the same z (the z component of pos); see Gotchas.

Core concepts

Apps, the process tree, and the window manager

Apps form a parent-child process tree rooted at the bootstrap app. An app creates a child with datumhue.app.spawn(). The window manager (WM) is itself an ordinary app — usually the bootstrap — that spawns and arranges the others.

Authority follows the tree. WM mutations (terminate_app, set_app_bounds, and so on) require the caller to be an ancestor of the target; attempting to manage a non-descendant raises an error. The bootstrap can manage everything. WM functions take an App handle (from datumhue.app.self(), app.spawn, or an event payload) — never a numeric id.

When startup produces errors, the runtime routes the launch to a package named fallback instead of the configured bootstrap. The fallback runs as the root app, reads the errors via datumhue.app.errors(), and otherwise inherits the bootstrap's root-app privileges.

The app window

Each app gets an auto-created root container on spawn:

Root Container (WM-managed bounds, overflow clipped, z-indexed)
└── Content Area (fills root)
    ├── your panels, images, labels, buttons...
    └── everything without an explicit parent lands here

The root container is the target for WM operations and an app cannot render outside it. The content area is where your UI lives: datumhue.ui.root:panel(), source:mount(), and the like auto-parent here when you build at the UI root.

datumhue.screen is scope-dependent. The bootstrap/WM app drives the system window; a regular app drives its own root container — same code, different scope:

The request_* calls are proposals, not setters: a regular app's request goes to the window manager, which answers it. The screen.width / screen.height properties report the size actually in effect.

Apps are stacked most-recently-focused first. Focusing an app brings it to the front; datumhue.app.is_focused() reports focus, and app_focused / app_unfocused events fire on changes. A newly spawned app auto-receives focus when its spawner can manage the currently focused app. Cursor state (visible, locked, icon) is stored per app and swapped on focus change.

Coordinate systems

Two conventions coexist. State them once and keep them straight:

Draw primitives place depth in pos.z — pos = vec3(x, y, z), larger z in front. When converting a coordinate between a Y-up API and the Y-down image API, flip Y.

Capabilities and permissions

DatumHue gates sensitive operations two ways, and the distinction matters:

• Permissions are boolean grants drawn from a fixed set: identity, screenshot, network, commerce, packages. They gate whole surfaces (e.g. identity gates the user-data accessors, network gates network-scoped messaging/documents, commerce gates the purchase API, packages gates install management — installing, uninstalling, and reading the installed-package library, while plain catalog browsing stays open). The catalog itself spans every connected registry: each creator publishes under their own namespace, and packages.list / packages.search aggregate all of them unless narrowed to one.
• Capability handles are unforgeable userdata that grant access to one specific resource — a directory, file, data mount, or HTTP mount. Possession of the handle is the grant, and the handle arrives through datumhue.args or a parent's app.spawn options.

A package's manifest declares the permissions it requires under capabilities. Before the entry script runs, the runtime requests each from the parent WM; if any is denied, the app refuses to start. So inside a running app, datumhue.app.has_permission(name) is always true for every declared permission. The manifest sets the required floor; an app may also datumhue.app.request_permission(name) for optional grants at runtime.

Both permissions and capability handles flow down the tree and only narrow. A child receives a permission only when the spawning parent passes it in permissions = { … } on app.spawn and the parent itself holds it; likewise a child receives a dirs / files / data_mounts / http_mounts grant only from the parent's own grants. A call from an app that lacks a required permission raises.

Physics needs no grant at all: each app simulates in its own worlds, and bodies, joints, queries, and gravity never interact across apps.

The app lifecycle

The script body is the app's init phase — it runs once on spawn. Read spawn-time arguments from datumhue.args.argv. Calls that wait on I/O (loading assets, installing packages) are fine in the body; execution resumes step by step as each completes (see Suspending calls).

Register a per-frame handler with datumhue.on_update(fn). fn(dt) receives seconds since the previous call (typically ~0.016; scheduler pressure can stretch it). At most one update handler is active per app — calling again replaces it; pass nil to clear it. Timer callbacks fire before on_update in the same frame.

What keeps an app alive depends on its kind. A UI app stays alive until something explicitly terminates it: it calls datumhue.app.terminate(), a managing app calls datumhue.wm.terminate_app(child), the parent cascades, or it crashes (see When a callback errors). The body returning or having no callbacks does not reap it. A service app (no UI) is kept alive only while some callback is still registered; print("hi") runs and exits. Everything that counts as "registered" is one of these:

• the on_update handler;
• a timer that hasn't fired for the last time or been cancelled;
• a subscription of any kind — events, messages, channels, document watchers and the collection / counter feeds built on them, package-catalog changes, text / key input capture;
• a callback attached to something the app owns — element handlers, collision callbacks, streamed-chunk callbacks, animation callbacks, data error handlers, route and dialogue hooks;
• a suspending call that is still waiting: an app is never reaped in the middle of a paused call, however long the wait.

When the last of these is gone — every timer done, every subscription unsubscribed, no update handler, nothing in flight — a service app ends.

Discarding a subscription's handle does not unsubscribe. The value a subscribe call (or a timer) returns is a control handle, not the registration itself: letting it go out of scope leaves the callback registered — still firing, and still keeping a service app alive — with no way left to stop it short of terminating the app. Keep the handle and call :unsubscribe() when you are done with it.

A spawn that fails still ends in app_terminated. app.spawn returns the child's handle immediately; a child spawned from the catalog starts running only once its package arrives. If the package can't be delivered or can't run, the child never starts: its handle reports not alive and app_terminated fires for it — the same terminal signal as for a running app's exit, so one handler covers both.

When an app terminates, all its descendants terminate too (cascade) and everything it owns is cleaned up. If the terminated app had focus, the engine auto-focuses the surviving app with the highest z-index. To flush state on the way out, register a handler with datumhue.on_terminate(fn): it runs once, inside a short bounded time budget, before the cleanup — but not on a crash — and it cannot cancel the termination. Registering it does not keep a service app alive.

When a callback errors

One rule covers every callback shape: an error that escapes a callback crashes the app. The entry script, the on_update handler, timer callbacks, UI handlers such as on_click, events.on and messaging subscription callbacks, document watchers, and collision callbacks all behave identically — the error is reported in the client's log output with the app's name, and the app terminates with the usual cleanup: descendants cascade, everything the app owns is removed, and none of its callbacks fires again. Nothing is selectively unregistered; there is no middle ground where a timer stops but the app lives on. Other apps are untouched, and a managing app observes the same app_terminated event as for any other exit. When the crashed app is the root of a datumhue run invocation, the process exits with a failure code.

To survive an error, catch it where it can happen: wrap the failure-prone call in pcall inside the callback and handle the result — a caught error crashes nothing. A callback that one of your own calls invokes on the spot (a router page builder, a book template function) raises at that call site instead, so a pcall around the outer call catches those too.

Suspending calls

Some datumhue.* calls are suspending: they pause the calling code — and, while paused, the app's per-frame work — until their result is ready, then continue. They do not block the OS thread: the renderer keeps drawing this app's last state and other apps keep running. For local or fast operations this is sub-frame and unnoticeable; waiting on a slow network, a heavy query, or a user dialog can be visibly long.

Suspending calls return their result the ordinary way — local t = b:text(), no callback to wait on. The API reference flags each suspending call. Treat a flagged call as one that can pause; don't put it in a tight loop assuming it is free.

Most waits are handles, not pauses. Request/response operations — HTTP requests, file writes and metadata reads, storage and document reads and writes — start their work the moment you call them and return a handle immediately, before the result exists. Reading a result field off an unmaterialized handle raises; await it with the chainable :ready() (which suspends, returns the same handle, and raises if the operation failed), or probe its state field, which never raises or suspends. Asset handles work the same way: they come back at once and load in the background. Because the work starts at the call, several operations run concurrently — start them all, then wait once with the datumhue.ready barrier, which resolves when every handle in the batch is ready and raises on the first failure:

local store = datumhue.storage.open()
store:set("alpha", datumhue.bytes("first")):ready()
store:set("beta", datumhue.bytes("second")):ready()

local a = store:get("alpha")
local b = store:get("beta")

datumhue.ready({ a, b })
print(a.value:text(), b.value:text())

For straight-line code, chain the barrier onto the call — file:write(bytes):ready() writes and confirms in one expression. Dropping a handle without awaiting it is allowed: the operation still runs; you have chosen not to observe its outcome. Chart state that settles as part of rendering a frame — a scale's domain, data-space conversions — is nil while unresolved; read it again on a later frame rather than waiting on it.

Suspending inside callbacks. Every callback shape can suspend — the entry script, on_update, timers, UI handlers (the Navigation example pushes a route from inside on_click), event and messaging subscriptions, document watchers. An app's callbacks never interleave: they run one at a time, in order, and each runs to completion before the next starts, so a flow of several suspending calls in one callback executes start-to-finish with nothing else of yours running in between. That no-interleaving guarantee is the recommended shape for a long flow: write it as straight-line code in a single callback. The cost is that while one callback is paused, everything else the app has to run waits in line behind it — a second click queues a second invocation that runs after the first completes, and a repeating timer keeps firing on schedule, queueing one invocation per fire, delivered back-to-back once the paused callback finishes. Guard a flow that must not run twice with a flag. The per-frame handler is the one thing that never piles up: at most one on_update invocation is in flight or waiting at a time; beyond that, frames skip it and the elapsed time accrues, so the next invocation receives the full time since the previous one as its dt. Your own coroutines don't change any of this: a suspending call inside a coroutine you resume still pauses the whole app's Lua, not just that coroutine.

There is no timeout. A suspending call stays paused until its result arrives, however long that takes — datumhue.ready on an asset that never arrives waits indefinitely, and request_permission waits for as long as the parent takes to answer (a parent prompting the user may take arbitrarily long). This is deliberate: the runtime cannot know which waits are legitimately long, and there is no timeout to configure. pcall does not shorten a wait either — waiting is not an error, so there is nothing to catch. A suspended app is still an ordinary app: the renderer keeps showing its last state, it can be terminated normally, and it never stalls other apps or the client.

Sessions

A session is an identifier attached to every launch, so concurrent launches can be told apart. Apps read the resolved value via datumhue.app.session().

Each launch is independent by default — there is no implicit carry-over. A launch can name a session explicitly, or resume the most recently used one. On the desktop a launch is one process invocation; in a browser a launch is one tab, with the session sticky across reloads of that tab and cleared when it closes. The exact launch syntax is in datumhue --help.

Packages

A package is a directory with a package.kdl manifest plus a strict layout of code and content. The client loads a package as a single unit — the entry script, every require-able module under lib/, and every asset under assets/ come from the same tree.

Layout

my-package/
├── package.kdl          # manifest — name, version, kind, requires
├── init.lua             # entry — app's main / library's exported table
├── lib/                 # module tree, .lua only, any depth
│   ├── util.lua         #   → require("util")
│   ├── sub.lua          #   → require("sub")
│   └── sub/
│       └── leaf.lua     #   → require("sub.leaf")
└── assets/              # content, any file type, any depth
    ├── player.png       #   datumhue.package:dir():read("assets/player.png"):image()
    ├── audio/boop.ogg   #   datumhue.package:dir():read("assets/audio/boop.ogg"):audio()
    └── data/grid.csv    #   datumhue.package:dir():read("assets/data/grid.csv"):csv()

The loader picks up only package.kdl (required), init.lua (the entry — the app's main, or what require("<libname>") returns), lib/**/*.lua (the module tree; non-.lua files under lib/ have no runtime meaning), and assets/**/* (everything else). Anything else at the top level — README.md, docs/, dotfiles — is silently skipped. deps/ at the root is reserved and populated by the resolver under deps/@scope/name/; you never author it.

An optional .dhignore at the root layers gitignore-style glob exclusions over the layout. It is itself a dotfile, so it never ships in the bundle.

The manifest

name "@alice/my-app"
version "0.1.0"
api_version "*"
kind "app"
author "Alice"
description "A tiny example."
icon "assets/icon.png"
license "MIT-0"
tags "demo" "example"
capabilities "network" "identity"
sealed #false
service #false

name is the package's identity in the catalog, written @scope/name. The scope binds the package to the entity that owns it — an individual or a team — and is enforced at publish against the publisher's verified sign-in. Both segments are lowercase letters, digits, _, or -, starting with a letter or digit; _ folds to -, so @a/foo_bar and @a/foo-bar are one identity. version is a SemVer version; api_version is a SemVer constraint on the client API the package was built against. kind is one of:

• app — launchable, has init.lua.
• library — require-able, has a lib/ tree.
• asset_pack — data only (themes, books, datasets, fonts, shaders, media). An open-list content_type tag (e.g. "theme", "dataset") refines it for discovery and validation. It is valid on an asset_pack and on an app whose substance is content (an interactive "book"); only a library rejects it.

The optional catalog fields round out the manifest. author and description are display strings; icon, readme, and screenshots are package-relative paths to images and a README; tags is a list of discovery keywords. license is the package's license as an SPDX id. A free package must declare one the platform may redistribute it under; the accepted ids, and which of them qualify, are the Package licenses chapter. monetization is "free" (the default) or "paid" — a flag, not a price: the listing price is store state, set and changed at any time with datumhue pkg price, without republishing. A paid package that has not been priced yet is gated but not purchasable. A paid app must be sealed. A paid library or asset pack is the opposite by design — never sealed: its sale delivers the source into the buyer's project as a perpetual embed license, to use and adapt under the seller's terms and ship inside the buyer's own packages.

Two manifest flags change how an app runs:

• service #true — the app runs without a UI surface. No root container is created, and the UI-producing sides of the datumhue table (ui, draw, image, scene, screen, theme, input, wm, physics, …) are not registered — calling them errors. datumhue.app.is_service() reports the live value. Valid only on kind "app".
• sealed #true — the app opts out of external introspection. A consumer that loads a sealed package sees its manifest metadata but pkg:dir() returns nil; the running app still reaches its own files. Sealing is a trust signal, not encryption — anyone with the bytes can unpack them offline. Only an app may seal; libraries and asset packs are delivered as source.

capabilities declares required permissions; see Capabilities and permissions.

A networked creation names its meeting point — the service its players' copies contact to find each other — with meeting-point "https://play.example.com" ca-cert="assets/ca-cert.pem". The networked runtime connects only there, reading no address from its environment, and the CA file (omit it for a publicly-trusted certificate) ships inside the package so the binding signature covers it. Valid only on kind "app"; every other client ignores it.

Archives

The same layout can travel as a single file: a .dhpkg archive is a plain zip whose entries are the package-relative paths. A packed archive's content hash matches the source tree's hash, so packing and unpacking are byte-identical round trips.

require and modules

Each app has a sandboxed require that reads module source only from its own package (plus resolved deps). Names are absolute from the package root and dotted — lib/ is implicit and never spelled. There is no relative form, no ./sibling, no package.path.

require("foo")            -- lib/foo.lua
require("foo.bar.baz")    -- lib/foo/bar/baz.lua

One name, one file: a module named sub is lib/sub.lua, sitting beside whatever lib/sub/ holds. A directory on its own is not a module.

A leading @ switches lookup into the dependency namespace: a dependency is addressed by its @scope/name identity in slash form, optionally followed by a module path under the dep's lib/ tree.

require("@alice/greeter-lib")                  -- the dep's entry (its own init.lua return)
require("@alice/greeter-lib/messages/welcome") -- a module inside the dep's lib/ tree

A dependency may declare an exports list in its package.kdl (exports "util" "messages.welcome"): when present, only the listed modules answer deep requires like the second form — the rest of its lib/ is its own business. The entry is always reachable, and a package's own requires are never gated.

Each module runs once per app; repeat calls hand back the same value. A module that returns nothing yields true. Circular requires surface as a runtime error rather than deadlocking. A typo or missing module fails with an error naming the exact path it looked for — require: module 'x' not found in package (looked for lib/x.lua) — and a module a dependency keeps private fails with is not exported by @scope/name and the list that is.

For loading an exact path rather than a dotted name, a Dir or File handle exposes dir:require(rel) / file:require(), which compile the literal path's bytes as Lua — no lib/ prefixing, no .lua fallback. Handle-scoped requires are separate from the global dotted require.

Dependencies

Declare each dependency in the manifest by its @scope/name identity. Only library and asset_pack content is eligible — apps have their own lifecycle and are launched, not required. A dependency resolves from one of two sources:

requires {
    package "@alice/greeter-lib" version="^1.0"   // from the registry (default)
    package "@studio/art-pack" version="~0.3" namespace="brand"  // registry, other namespace
    package "@me/in-progress-lib" workspace=#true // from a local workspace member
}

A registry dependency carries a SemVer constraint and resolves to a published version; an optional namespace looks it up in a different namespace. A workspace dependency (workspace=#true) carries no version — it resolves to the matching member of the enclosing workspace.kdl (below), letting you iterate on a library and the app that uses it together before either is published. At publish the workspace marker is stripped: the dependency is by then published, so the on-wire manifest only ever carries registry references pinned to the member's version.

Resolved dependencies graft into the consumer under deps/@scope/name/. Reach into a dep from Lua with its @scope/name identity; read its assets through the standard Dir methods, e.g. datumhue.package:dir():read("deps/@studio/art-pack/assets/player.png"):image().

datumhue pkg update resolves the registry dependencies and writes package.lock.kdl, pinning each to the exact published content it resolves to (yanked versions are skipped) and recording each workspace dependency as a marker. datumhue pkg push then publishes against that lock without re-resolving — it fails if a pinned dependency has since been yanked or removed, pointing you back at pkg update. To move onto newer or un-yanked dependency versions, run pkg update, review the lockfile diff, and push. datumhue pkg outdated lists dependencies with a newer or yanked pin.

A paid dependency works differently: buy it once (the store's Creator shelf), and pkg update delivers its source into your project at deps/@scope/name/ — yours to read, adapt under the seller's terms, and keep; your own backups cover it from then on. The delivered tree is the dependency: it ships inside your published package, your users never fetch it separately, and the lock records it as vendored provenance rather than a pin. Delete the tree and run pkg update to re-deliver a fresh copy.

Conflicts are errors: if two transitive requirements cannot be satisfied by one version of a dep, resolution refuses to proceed. Missing deps, version mismatches, and using an app as a dependency all fail with a clear message before the first line of Lua runs.

Workspaces

A workspace.kdl at the root of a tree of related packages declares which directories are its members — the packages you develop together and publish as a unit. It is the sole source of workspace membership; without one, every dependency resolves from the registry.

workspace {
    namespace "acme"        // default publish namespace for members
    member "chart-lib"      // a member directory, relative to this file
    member "apps/*"         // a glob matching every immediate subdirectory
    member "theme" namespace="brand"  // a per-member namespace override
}

A workspace=#true dependency resolves to the member with that @scope/name. datumhue pkg update --workspace refreshes every member's lockfile in one pass, and datumhue pkg push --workspace publishes the members in dependency order — a library before the app that depends on it — so each published package pins its dependencies' real published content. It is idempotent: members already published at their version are skipped, so re-running after a failure resumes. --dry-run prints the order without publishing anything.

Maintaining a published release

Published versions are immutable — you never overwrite one. To retire a release that should no longer be installed, datumhue pkg yank marks a specific version yanked: it drops out of fresh resolutions, pkg update moves dependents off it, and pkg outdated flags anyone still pinned to it — while installs already pinned to that version keep launching. Yanking is reversible. Before you yank, datumhue pkg dependents lists the published packages that depend on the one you're about to pull, so you can gauge the blast radius first.

Package handles

A Package handle is the runtime representation of a package — the running app's own bundle (datumhue.package) or another loaded via dir:load_package / file:load_package:

print(datumhue.package:name(), datumhue.package:version())

local addon = datumhue.args.files.addon:load_package()
print(addon:name(), addon:version(), addon:kind())
if not addon:is_sealed() then
    print("entry source:", addon:dir():read("init.lua"):text())
end

A handle exposes manifest metadata (name, version, kind) and a read-only dir() over the bundle's files; dir() returns nil for a sealed package loaded from outside. Content access goes through that directory using the standard Dir methods and the Bytes decoders. Handle equality is identity-based — loading the same path twice yields two unequal handles; compare .name / :version() / :kind() instead.

Working with the API

The sections below cover the models behind each part of the API. For exact signatures, see the API reference alongside this guide.

A few conventions run through all of it:

• Colors are Color values from datumhue.color(...). The callable table accepts a hex string ("#RRGGBB" / "#RRGGBBAA"), RGB/RGBA floats, or named constructors (color.rgb, color.rgba, color.hex, color.hsl). Scripts usually bind local color = datumhue.color.
• Typed handles are returned by every creation function (Image, Atlas, Sprite, DrawCanvas, DrawPrimitive, TileMap, Scene, SceneNode, UiElement, Material, Shader, …). Each carries the methods for its API and supports == and tostring() — nothing else. They are opaque; don't treat them as numbers.
• Texture creation vs display. image.new, draw.new, and scene.new only allocate a render target. Call source:mount(opts) to display it — the same texture can be shown multiple times.
• Parameter style. Retained-mode APIs (draw, scene, ui) take option tables ({x = 10, y = 20}). Picture drawing takes positional arguments.
• Angles are radians everywhere. Errors are raised, not returned — wrap fallible calls in pcall.

Drawing and 3D

Three rendering surfaces, all displayed via source:mount():

• datumhue.draw — retained 2D vector drawing, center-origin and Y-up. Primitives (canvas:rect, canvas:circle, …) persist across frames; update their properties with prim:update(opts) rather than redrawing.
• datumhue.image — a raster Image, top-left origin and Y-down. One type covers both a framebuffer you draw into and loaded/encodable pixel data: draw by recording a picture() and replaying it with image:apply (the update is atomic; reuse one picture with picture:reset() then picture:clear()), read pixels with image:get, and persist with image:encode_png. Slice an image into a cell grid with image:atlas to feed sprites (canvas:sprite), tile maps (canvas:tilemap), and bitmap fonts (picture:set_font).
• datumhue.scene — retained 3D with PBR materials, HDR, bloom, fog, atmosphere, voxels, and glTF models. The camera mirrors a standard transform (a rotation field plus a look_at method).

The two 2D systems split by idiom. draw is retained vector: objects you create, keep, and mutate, in Y-up center-origin space. image plus Picture is recorded raster: record commands into a picture, replay them onto the image with image:apply, in Y-down top-left pixel space. If you are used to clearing and redrawing each frame, that idiom is a Picture plus reset(); if you think in persistent objects that move, that is draw.

They also split on blending. Draw primitives composite with standard alpha blending — there is no per-primitive blend mode. For other compositing (additive glow, multiply, screen), either work in pixels — picture:blit takes a blend mode — or give the primitive a shader material and compute the effect in its fragment program, feeding the layers to blend through its channel textures.

Physics attaches to draw and scene primitives via prim:add_body(opts). The engine owns a body's position each frame, so drive bodies through the prim.pos and prim.velocity properties, whose assignment updates the visual and the physics state together, not via prim:update({pos = …}).

Audio (datumhue.audio) covers waveform synthesis and sample playback; the generated reference carries its surface. Mixing is three factors multiplied together — the master volume, an optional named bus (audio.bus), and each instance's own gain — so one bus knob ducks everything routed through it without touching the instances, and a bed switch cannot desync the duck. A one-shot given a position (at, heard from listener) arrives panned toward its side and quieter with distance; omit at and it plays centered and unattenuated, from everywhere.

Shaders

datumhue.shader.new() returns a Shader you apply anywhere a surface accepts a material option — UI panels, 2D draw primitives, 3D meshes, and scene post-processing all take the same handle:

datumhue.ui.root:panel({..., material = glow})
canvas:rect({..., material = gradient})
scene:cube({material = noise})
scene:mount({..., material = scanline})  -- post-processing

Beyond the presets, bytes:shader compiles your own fragment program (WGSL, or WESL extended syntax) into the same kind of handle. The source defines dh_fragment(uv) and reads auto-fed globals — dh.time, and a per-primitive dh.resolution / dh.mouse (each shaded primitive sees its own size and its own cursor position) — plus the uniforms you declare at creation (written later with shader:set) and up to four dh_channel textures fed from images, draw canvases, or scenes (shader:set_channel). Compile errors raise immediately with the failing source line, and shader:reload recompiles live, keeping the previous program when the new source is broken — an edit-save-reload loop. A dh_fragment that never returns can stall rendering and may trigger a GPU driver reset — keep it free of unbounded loops.

User interface

datumhue.ui builds flex-laid-out widgets — panel, button, label, image. Each widget is a method on its parent UiElement (parent:button{...}, some_panel:label{...}); build at the top level with datumhue.ui.root (datumhue.ui.root:panel{...}). Every constructor and elem:update share one set of layout and style options.

Every dimensional option (positions, sizes, gaps, padding, margins, borders) accepts a number or a string:

padding, margin, and border accept a single value (all four sides), a named table ({left = 10, top = 4, …}), or the CSS array shorthand ({a}, {a,b}, {a,b,c}, {a,b,c,d}). border_radius takes the same shapes per corner. Anchoring an element (left / right / top / bottom) switches it to absolute positioning; otherwise it participates in its parent's flex layout. panel and button default to themed padding and rounding — pass padding = 0 / border_radius = 0 to opt out.

Navigation

panel:router() turns a region into a navigation stack. You declare routes from builder functions and move between them; the router keeps backgrounded pages alive (hidden), so going back restores their scroll position and widget state instead of rebuilding from scratch.

local content = datumhue.ui.root:panel({ left = 20, top = 20, right = 20, bottom = 20 })
local router = content:router()
local list = router:route(function(page)
    page:button({ text = "Open item 1", on_click = function() router:push(detail, { id = 1 }) end })
end, { title = "Items" })
detail = router:route(function(page, params)
    page:label({ text = "Item " .. params.id })
    page:button({ text = "Back", on_click = function() router:pop() end })
end, { title = "Detail" })
router:show(list)

route(builder, opts) returns a Route handle; navigate with push (drill in), pop (back), replace (swap the top), to_root (back to the start), and go (jump to a route — popping to it if it's already on the stack, else pushing). A page builder receives its page element and the params passed to the navigator (small identifiers, not data — fetch the data from your own store). router.depth, router.active, router.params, and router.can_go_back describe the current state; compare router.active to a route handle to highlight the current tab.

Tabs are just several root routes switched with show — each keeps its own retained sub-stack, so switching tabs and coming back restores where you were. Routers are independent and nest: a route's page can create its own router.

A route may declare on_enter (called once the page is built — start per-page work here) and on_leave (called before the page is destroyed; return false to veto and keep it, e.g. to confirm discarding unsaved edits). Navigating moves keyboard focus into the new page (a screen reader announces its title) and restores focus when you go back.

Theming

datumhue.theme drives appearance through a token map: widgets and chart primitives reference named color and metric tokens (panel_background, chart_axis, padding_medium, …) rather than hard-coded values. The full token list lives in the generated reference.

datumhue.theme.pin(datumhue.theme.default_dark())          -- built-in theme
datumhue.theme.pin(datumhue.theme.default_light(), child)  -- a managed child

local custom = datumhue.args.files.mytheme:read():theme()  -- a custom theme file
datumhue.theme.pin(custom)

Partial overrides are valid — a theme only defines the tokens it changes; the rest fall back to the built-in default. Child apps that haven't set their own theme inherit from the nearest ancestor that has, and update reactively when that ancestor changes. Themes can also bind default shader materials to widget types via widget_shaders; on creation, a widget resolves its surface in priority order: per-widget material > theme widget_shaders slot > solid background color.

Custom themes are KDL documents decoded via file:read():theme() / dir:read(rel):theme(), returning a Theme for theme.pin:

colors {
    panel_background 0x1a1a2e
    text_primary     0xeaeaea
    accent_primary   0xe94560
}
metrics {
    padding_medium 12
    border_radius  6
}

Colors are 0xRRGGBB hex. A theme can also define GPU materials in a shaders block and bind them to widget slots; the block shapes and every token live in the generated reference.

Display and input

datumhue.screen is scope-dependent (see The app window). Four sizing knobs compose, from OS-level outward:

Each knob is a request, not a setter: the proposal goes to the window manager, which answers it. Read what is actually in effect from the screen state properties. The OS display scale (DPI, Retina, fractional scaling) is always honored on top; the reported screen.width / screen.height are already in logical units.

datumhue.input reads keyboard, mouse, and gamepad state. Input is focus-gated by the same can_manage rule as lifecycle events: only the focused app and its ancestors receive real input state. Any other caller sees inert values (booleans false, positions nil, vectors {x=0, y=0}, triggers 0.0) so background apps cannot observe keystrokes. Key names are physical keys (layout-independent), written in lowercase snake case: "a" is the QWERTY-A position regardless of layout. "shift" / "control" / "alt" are side-agnostic aliases; use "shift_left" / "shift_right" (etc.) to distinguish sides. Cursor mutations are per app and apply only while focused; state is saved and restored on focus change.

Filesystem and data capabilities

Apps never see host paths. They navigate opaque Dir and File handles through a small set of methods — there is no ambient open(path). Handles arrive three ways:

• From the launcher, under datumhue.args — directories, files, and remote mounts the launch granted. The exact launch syntax is in datumhue --help (desktop) or the browser launcher's URL params.
• From a file widget — ui.root:open_button{mode=…, on_pick=…} opens a file / directory dialog when the user clicks it and delivers the chosen File / File[] / Dir to on_pick; save_button{source=…, on_save=…} writes bytes to a chosen file and hands back a read-only File. Returned handles are indistinguishable from launcher-supplied ones.
• From child-spawn inheritance — a parent hands handles to a child it spawns.

Every handle exposes the same methods regardless of origin: dir:list, dir:read(rel), dir:write(rel, bytes), file:read(), file:write(bytes), and the full set of Bytes decoders. Remote mounts connect lazily on first use; failures surface to the specific Lua call, not at startup. Data mounts (a SQL surface, under datumhue.args.data_mounts) open and authenticate lazily on the first mount:query(...).

Bytes and encoding

datumhue.bytes is the one handle for opaque byte payloads. Every API that produces bytes (file reads, HTTP responses, encoder output) returns a Bytes; every API that consumes bytes (request bodies, file writes) accepts one. All decoding lives on the Bytes userdata — :text, :json, :image, :csv, :parquet, :kdl, :theme, :audio, … — there is no separate decoder namespace.

Construct a Bytes from a Lua string via the namespace's call form, or from a structured value via an encoder constructor (datumhue.bytes.json(v) / .kdl(v) / .msgpack(v)). KDL maps to and from Lua tables like this (applies to bytes:kdl() and datumhue.bytes.kdl(value)):

The mapping preserves structural meaning, not textual layout — type annotations, comments, ordering, and spacing are not round-tripped. To omit a key, set it to nil; an empty Lua table encodes as a bare node.

Tabular data

Tabular data sits behind opaque DataHandle userdata from bytes:csv() and bytes:parquet() — typically file:read():csv() or dir:read(rel):parquet(), or datumhue.bytes(literal):csv() for an inline CSV. Methods that read data are suspending: if the source is still loading, the call pauses and resumes once it is ready.

local sales = datumhue.bytes([[
month,region,revenue
1,North,45000
1,South,38000
2,North,52000
]]):csv()

local top = sales:query(
    "SELECT region, SUM(revenue) AS total FROM data GROUP BY region")

Queries are lazy: nothing executes until a consumer reads them, via rows(), batches(), count(), or binding to a mark. Results stream rather than materializing full columns into Lua tables.

Charts

datumhue.chart composes charts from shared scales (data → pixels) and a plot area carved out of a DrawCanvas. Marks render inside the plot area using its scales, so hand-drawn primitives and chart primitives coexist on one canvas.

Scales exist independently and own only the data domain: multiple marks — and multiple plot areas — can share one scale to stay aligned under pan/zoom, while each plot area assigns the scale its own pixel range from its geometry. Two differently sized plots sharing an x scale therefore pan together without sharing pixels, and everything reflows when an area resizes. Marks bound to DataHandle instances stream with pixel-aware downsampling — full columns are never materialized.

local color = datumhue.color
local vec3 = datumhue.math.vec3

local canvas = datumhue.draw.new({ width = 800, height = 400 })
local xs = datumhue.chart.scale.linear({ domain = "auto", nice = true })
local ys = datumhue.chart.scale.linear({ domain = "auto", nice = true })

local plot = canvas:chart({
    pos = vec3(0, 0, 0), width = 800, height = 400,
    margin = { left = 60, right = 20, top = 20, bottom = 40 },
    x_scale = xs, y_scale = ys,
})

local h = datumhue.bytes("x,y\n1,10\n2,20\n3,15\n"):csv()
plot:line({ data = h, x_column = "x", y_column = "y", color = color("#4488ff") })

Chart primitives render in fixed depth layers, back to front: background → grid → area → line → bars → points → reference rules → text overlays → axis spine/ticks/labels → legend. Ties within a layer resolve by insertion order. There is no z option — choose the primitive type to land in the right layer, and construct primitives in the order you want them stacked.

Aggregating marks — histograms, 2D-density and categorical heatmaps, box plots, and multi-series bars — compute their bins, group-bys, and summaries engine-side against the source, and re-aggregate over the visible domain when a scale zooms. Interaction is opt-in per area: pan/zoom, crosshair readouts, and a brush gesture that delivers the selected data-space range to a callback — re-query other charts' sources from it to crossfilter. canvas:charts lays out a grid of plot areas for faceting (cells passed the same scale handle stay linked under pan/zoom), and scale:animate eases a domain change for animated transitions.

Storage

datumhue.storage.open(label?) returns a Storage handle for persistent key→bytes storage that survives across sessions. Your package is the identity — the same package reaches the same store across runs, instances, and upgrades, and no other app can address it. Optional labels open independent sub-stores of the same identity. How the package arrived qualifies the identity: a registry-installed package, a license-bound creation, and a locally run directory or script each get their own store, even under the same package name — so local development never sees (or risks) an installed package's data, and a locally run package claiming an installed package's name gets an empty store, not that package's data. Locally run code is only as private as your machine: any local app that claims the same name shares the same local-tier store.

open_scoped(label?) opens a store shared by every package under your publisher scope — cooperating apps from one publisher coordinate through it without any exchange. open_shared(uuid) is the explicit cross-scope mechanism: every app passing the same UUID reaches the same store, so a UUID hard-coded in published source is public, and a UUID kept out of the source is a secret capability (datumhue.uuid() mints one). Values are opaque Bytes; the handle methods are suspending.

Identity

datumhue.identity reports who the current user is, if anyone has signed in. sign_in, sign_out, and is_signed_in are available to every app — but when a regular app calls sign_in / sign_out, the shell receives an app_identity_sign_in_request / app_identity_sign_out_request event and decides whether to honor it. Outcomes surface through datumhue.events.

The accessors that expose user data — sub, issuer, email, name, and claims — require identity permission. The user's credential stays server-side: when an HTTP mount forwards it, the provider attaches it itself (see HTTP).

Messaging, events, and documents

Three ways apps coordinate:

datumhue.messaging — topic-based pub/sub with two scopes. scope = "local" (default) is a shared in-process bus across apps on this client; topic names are not namespaced, so pick a hard-to-guess name for a private channel. scope = "network" also reaches other clients, is opt-in, and requires network permission. In both scopes, a publisher that subscribes to the same topic does not receive its own messages.

datumhue.events — events.on(name, callback) subscribes to a system event; the callback gets the payload table. Delivery is scoped: app-lifecycle events (app_spawned, app_focused, app_bounds_changed, screen requests, …) reach an app only for apps it can manage — its descendants and itself — and each payload carries app and parent. Identity events reach every app. A child's permission request is delivered to the parent WM as the request handle on the app_permission_request payload; the WM answers it with request:grant() / request:deny(), or stashes it to answer later (e.g. behind an approval modal) — dropping it unanswered denies the request. connectivity reports whether a deployment connection is up: it fires once on subscribe with the current state and again on every transition, so a creation can start offline and light up its shared layer when its meeting point is reached; a build without a network layer reports offline once and never flips. The full event-name catalog and payload fields are in the generated reference.

datumhue.documents — shared key-value state with change subscriptions. scope = "local" (default) is an in-process store shared by apps on this client for the process lifetime; scope = "network" replicates with other clients, converging concurrent writes last-write-wins, and requires network permission. Constructors return a Document handle whose methods (set, get, subscribe, …) route by scope. Network keys are /-separated paths: writing a key supersedes everything under it, and delete_prefix removes a whole subtree. Sharing access goes through grants: doc:grant{...} mints a DocumentGrant — bound to a recipient's identity, or bearer when no recipient is named — whose :encode() string travels over any channel and opens with datumhue.documents.open(...). Grants attenuate: a holder can delegate a narrower one (read-only, a key subtree, a shorter validity) but never a wider one. Every user also has a communal document derived from their durable identity (documents.identity, gated on the identity permission): your own section is always writable, others' sections need a grant from them.

HTTP

An app makes HTTP requests through a granted HttpMount capability — datumhue.args.http_mounts.<name>, or one a parent forwarded. Possession of the handle is the grant, and the handle arrives only from those two sources. An operator pins each mount to one origin, so the app supplies a mount-relative path and reaches exactly the configured destination. mount:get(path) / post / put / patch / delete / head are suspending — they pause the calling coroutine until the response arrives, blocking no frame. The methods share one option-table shape; the body, when present, is a Bytes handle. A response's .body is itself a Bytes, so decode it inline: mount:get("/items").body:json(). Credentials are attached provider-side per the mount's configuration; the app never handles them.

The package catalog

datumhue.packages browses the packages the client knows about. Reads are synchronous and return whatever the client has at the moment of the call; the catalog stays current automatically, and on_change subscribes to live changes. Read functions return opaque PackageRef userdata — also the value app.spawn({package_ref = …}) accepts.

Books and documents

A book is content first: pages written as .dhml (markdown prose whose kdl code fences hold declarative elements) or as .kdl (one element tree under a page node), listed by a book.kdl at the book's root. Load one through the filesystem capability you already hold — file:book() for a single page, dir:book() for a directory — and book:mount{} renders the current chapter into a scrollable page view. Multi-chapter books mount with a chapter sidebar and a navigation row; pass toc = false / nav = false for a bare page view.

Documents stay data until they need behavior. Give an element an id and the hosting app binds it live: book:element(id) hands back the same typed handle the constructor would have returned, so a button takes on_click, a chart's plot takes new marks, and a slot element is an empty container to mount anything into. Markdown headings register their slugs in the same id namespace; book:go(target) jumps to an anchor or switches chapters.

Prose and properties may carry {{ expression }} templates — Lua evaluated against the app's globals on each render — and the if / for nodes render conditionally and per-item. book:refresh(id?) re-renders a subtree or the whole page against current state. A page can also carry its own code: a lua fence (or a script node) runs once when the book loads, in the app's environment, and a kdl fence mounts as live elements. Add a source mode to either fence to show the code as an inert listing instead, or echo to show the listing and keep it live — so a book can teach the very syntax it is built from.

Scripts make a book an app: a package whose pages carry them is kind "app" with content_type "book", while a script-free book is a plain asset_pack that any app — such as the bundled reader — opens with dir:book(). To ship a book that opens on its own, make it a kind "app" package that bundles its pages and mount it from init.lua:

pkg:dir():book():mount({ toc = true, nav = true })

pkg:dir() is the running app's own bundle, so this reads the bundled book.kdl and chapters and renders them without a separate reader — the same on a connected workstation or a fully offline one. datumhue pkg check validates a book package end-to-end — manifest, pages, includes, and referenced files. The full element reference lives in the Documents (DHML) area of this documentation.

The Lua environment

DatumHue runs a safe, sandboxed Lua interpreter. Most of Lua 5.3/5.4 works as expected, with these notes:

• Available standard library: math, string, table, coroutine, and the base functions (print, type, error, assert, pcall, tonumber, tostring, pairs, ipairs, select, next, setmetatable, getmetatable). string.format, string.find, string.match, string.gmatch, string.gsub, string.sub, and the rest of the string library are present; both string.sub(s, 1, 3) and s:sub(1, 3) work.
• Not available: os, io, loadstring, dofile. There is no filesystem or system access except through capability handles.
• load holds the standard Lua 5.4 contract (the compiled closure, or nil, errmsg) for string chunks, but is text-only: binary chunks are rejected whatever mode is requested, and reader-function chunks are not accepted.
• require is available in sandboxed form, scoped to the package — see require and modules. Apps cannot import modules across package boundaries.
• Random: math.random() gives a float in [0, 1); math.random(n) an integer in [1, n]; math.random(m, n) an integer in [m, n]. math.randomseed(n) seeds for deterministic sequences. Each app has an independent RNG state.
• Coroutines are fully supported.
• No weak tables, no __gc metamethods.

Tooling

The command-line tools (datumhue run, repl, pkg …, login, debug) document themselves — run datumhue --help or datumhue <command> --help for flags, arguments, and exit codes. The pieces of tooling worth knowing as an author are editor integration, testing, and debugging.

Editor integration

DatumHue ships no first-party language server or formatter; it leans on mature external tooling. datumhue pkg new and datumhue pkg refresh drop three files into your package root:

• datumhue.d.lua — LuaLS type annotations for the datumhue.* API, rendered from the exact surface your client version ships. Regenerate with datumhue pkg refresh after a client upgrade.
• .luarc.json — LuaLS workspace config wiring in datumhue.d.lua, lib/, and resolved deps/, and declaring datumhue a known global.
• .stylua.toml — formatter config matching the scaffolded style.

A package with a tests/ suite also gets tests/test.d.lua — annotations for the globals available inside test modules, documented in the Package testing area of this reference.

Install LuaLS and stylua once. Any LuaLS-aware editor auto-picks up .luarc.json from the package root, giving completion and type-checking against your client's real API.

Document pages (.dhml) are markdown with embedded kdl code fences, so any editor's markdown mode highlights them. In Helix, associate the extension in languages.toml:

[[language]]
name = "markdown"
file-types = [{ glob = "*.dhml" }, "md", "markdown"]

Testing

A package's automated tests live in its tests/ directory — module files named *_test.lua plus optional support modules under tests/lib/. datumhue pkg new scaffolds a passing example. The directory never ships: packing, publishing, and running all ignore it.

datumhue pkg test <dir> runs the suite inside the real engine. Test modules declare suites and tests with describe and it; a test body can drive the app across frames (wait_frames, wait_until), inject keyboard and pointer input, and read the package's own modules with require, asserting through expect matchers or plain assert. Results stream in TAP form and the exit code carries the verdict; name filters, --skip, and --list select what runs, and every run prints a seed that reproduces its random rolls via --seed. Suites for windowed apps open a window — wrap the invocation in a headless compositor (such as gamescope --backend headless --) to run them unattended, and judge wrapped runs by the printed summary. `datumhue pkg test

datumhue docs                            # Markdown to stdout
datumhue docs -o api.md                  # Markdown to a file
datumhue docs --format json              # structured JSON catalog
datumhue docs --format html -o doc.html  # this searchable HTML page
datumhue docs --open                     # build the HTML page and open it

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

MIT No Attribution

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

CC0 1.0 Universal is a public-domain dedication: the creator waives all
copyright and related rights in the work, worldwide, to the extent allowed
by law. It carries no patent grant, which is why DatumHue allows it only on
data-only asset packs. The canonical legal code is published by Creative
Commons as "CC0 1.0 Universal" at
https://creativecommons.org/publicdomain/zero/1.0/legalcode

# DatumHue Freeware Package License

**SPDX id: `LicenseRef-DatumHue-Freeware` — Version 1.2 — 2026-08-29**

This license covers a **package** distributed for DatumHue under the
SPDX identifier `LicenseRef-DatumHue-Freeware`. It applies to the
published package artifact — its code (compiled where the package is
sealed) and its assets — not to any DatumHue binary, which is covered
by its own license. It applies regardless of which DatumHue edition
runs the package: the platform client, the Personal or Indie edition,
or any other licensed DatumHue client.

---

## 1. Grant

The rights holder — the author named in the package manifest — grants
you, free of charge, a non-exclusive, non-transferable right to:

- **download and run** the package with any licensed DatumHue client,
  and
- **redistribute the published artifact as-is** to other DatumHue users
  as part of DatumHue's content distribution (including its
  peer-to-peer distribution), unmodified and in whole.

## 2. Reservations

All rights not expressly granted are reserved by the rights holder. You
may not:

- decompile, disassemble, or otherwise reverse engineer the package's
  code, or attempt to reconstruct the source of a sealed package;
- modify the package or create derivative works from it;
- extract its code or assets for use outside the package;
- redistribute it outside DatumHue's content distribution, or sell,
  rent, or sublicense it.

## 3. No warranty

The package is provided "as is", without warranty of any kind. To the
maximum extent permitted by law, the rights holder disclaims all
liability arising from its use.

## 4. Termination

This license ends automatically if you breach it. On termination you
must delete your copies of the package.

## 5. Governing law

This license is governed by and construed in accordance with the laws
of Sweden, without regard to its conflict-of-laws principles. Any
dispute arising out of or in connection with this license — including
questions about its existence, validity, interpretation, or
termination — is subject to the exclusive jurisdiction of the Swedish
courts, with Gothenburg District Court (Göteborgs tingsrätt) as the
court of first instance. The rights holder may nevertheless seek
injunctive or other interim relief to protect its intellectual
property rights in any court of competent jurisdiction.

Nothing in this section deprives a consumer of the protection of
mandatory consumer-protection law of the country where they reside,
including the right to bring proceedings in, and to be sued only in,
the courts for the place where they reside.

All rights reserved. There is no public license text for this id: the terms
are whatever the rights holder grants you when the package is provided to
you. Absent such terms, you have no rights beyond running the package
through the channel it was provided by.