add usage guide, installer and starter files to the repo

README.md

@@ -62,7 +62,24 @@ This repo eats its own cooking. Everything you see on the website is styled by t
 
 The site is live. No setup, no build, nothing to install: https://dssl-sable.vercel.app
 
-Clone this repo if you want to read the engine or run it yourself. Everything runs in the browser.
+Want the engine on your own page? Two tags:
+
+```html
+<script type="module" src="/dssl/boot.js"></script>
+<link rel="stylesheet/dssl" href="/styles/tokens.dssl">
+```
+
+Every `<link rel="stylesheet/dssl">` on the page gets fetched and applied automatically, and the engine keeps restyling the DOM live as elements come and go. That is the whole install.
+
+Or grab it from a terminal:
+
+```sh
+curl -fsSL https://dssl-sable.vercel.app/install.sh | sh
+```
+
+That drops a `dssl-engine/` folder with the engine, a starter token set, a tiny example stylesheet and a usage guide (also in `package/` in this repo). Plain zip if you prefer: https://dssl-sable.vercel.app/dssl-engine.zip
+
+Clone this repo if you want to read the engine. Everything runs in the browser.
 
 ## Repo layout
 

package/USAGE.md

@@ -0,0 +1,94 @@
+# DSSL engine — quickstart
+
+DSSL is a style language that runs in the browser. You write `.dssl` files, add two tags to your page, and the engine does the rest. No compiler, no build step, no CSS output. The engine walks your DOM live and writes styles straight onto the elements it matches, including elements that show up later.
+
+## 1. Get the engine
+
+Copy the `dssl/` folder from this package into your project, or grab it fresh from a terminal:
+
+```sh
+curl -fsSL https://dssl-sable.vercel.app/install.sh | sh
+```
+
+That drops a `dssl-engine/` folder next to you with everything you need.
+
+## 2. Wire it up
+
+```html
+<!doctype html>
+<html data-dssl-reset>
+<head>
+  <script type="module" src="/dssl/boot.js"></script>
+  <link rel="stylesheet/dssl" href="/styles/tokens.dssl">
+  <link rel="stylesheet/dssl" href="/examples/hello.dssl">
+</head>
+<body>
+  <h1>Styled by DSSL</h1>
+</body>
+</html>
+```
+
+What those lines do:
+
+- `data-dssl-reset` (optional) turns on the small built-in reset.
+- `boot.js` is the whole install. It boots the engine on page load.
+- Every `<link rel="stylesheet/dssl">` is fetched and applied automatically, in the order you list them. Tokens first, then your styles.
+- Inline styles work too: `<style type="text/dssl"> ... </style>`.
+- When booting is done the page fires a `dssl-ready` event.
+
+## 3. Write some DSSL
+
+`examples/hello.dssl` in this package:
+
+```dssl
+body {
+  background: #f5f0e4
+  color: #26201a
+  padding: 40
+}
+
+.card {
+  background: #fdfaf2
+  border: 1 solid #ddd2bc
+  radius: 6
+  padding: 24
+
+  hover {
+    box-shadow: 0 6 18 #26201a/16
+  }
+}
+```
+
+Bare numbers are pixels. States like `hover` are nested blocks. The engine keeps them working forever, even for elements added to the page later.
+
+## The JavaScript API
+
+`window.DSSL` is available after boot:
+
+- `DSSL.load(urls)` fetch and apply one or more `.dssl` files (fetched in parallel, applied in order)
+- `DSSL.apply(source, { name, scope })` apply a source string
+- `DSSL.compile(source)` parse and resolve without touching the DOM, returns `ok`, `errors` and stats
+- `DSSL.signal(name, value)` drive styles from JS with `@signal` conditions in your `.dssl`
+- `DSSL.refresh()` force a full recompute
+- `DSSL.replay(selector)` replay entrance motions on matching elements
+- `DSSL.errors` the last reported errors (also grouped in the console, with did-you-mean hints)
+- `DSSL.version` engine version
+
+## Scoped engines
+
+```js
+DSSL.apply(source, { scope: '#widget' })
+```
+
+gives one subtree its own engine, its own tokens and its own cascade. The playground on the live site is built exactly this way.
+
+## Files in this package
+
+- `dssl/` the engine. `boot.js` is the entry, `index.js` the public API.
+- `styles/tokens.dssl` the starter token set (colors, fonts, radii, shadows)
+- `examples/hello.dssl` a tiny starter stylesheet
+- `USAGE.md` this file
+- `LICENSE` MIT
+
+Live site: https://dssl-sable.vercel.app
+Source and full language docs: https://huggingface.co/EHS-Studio/dssl

package/examples/hello.dssl

@@ -0,0 +1,39 @@
+// hello.dssl — a tiny starter stylesheet
+// bare numbers are px, hover is a nested state, /14 at the end of a color is alpha
+
+body {
+  background: #f5f0e4
+  color: #26201a
+  padding: 40
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif
+}
+
+h1 {
+  color: #7c2d2d
+}
+
+.card {
+  background: #fdfaf2
+  border: 1 solid #ddd2bc
+  radius: 6
+  padding: 24
+  box-shadow: 0 2 6 #26201a/14
+  transition: 200
+
+  hover {
+    box-shadow: 0 6 18 #26201a/16
+  }
+}
+
+button {
+  background: #7c2d2d
+  color: #f9efdd
+  padding: 10 18
+  radius: 6
+  border: 0
+  transition: 200
+
+  hover {
+    background: #5e1f1f
+  }
+}

package/install.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+# DSSL engine installer
+#   curl -fsSL https://dssl-sable.vercel.app/install.sh | sh
+set -e
+BASE="https://dssl-sable.vercel.app"
+ZIP="/tmp/dssl-engine-$$.zip"
+
+command -v curl >/dev/null 2>&1 || { echo "DSSL installer: 'curl' is required."; exit 1; }
+command -v unzip >/dev/null 2>&1 || { echo "DSSL installer: 'unzip' is required."; exit 1; }
+
+echo "fetching the DSSL engine..."
+curl -fsSL "$BASE/dssl-engine.zip" -o "$ZIP"
+rm -rf dssl-engine
+unzip -q "$ZIP" -d .
+rm -f "$ZIP"
+
+echo ""
+echo "DSSL engine installed to ./dssl-engine"
+echo "read dssl-engine/USAGE.md to wire it into a page."