ed8a3145b3
Phase 1 of the hexagonal-architecture plan (dtoro/oikos plans/2026-08-15-hexagonal-architecture.md). Moves the delivery stack for the control-room UI into its own repo with its own pipeline: - web/ — Svelte 5 SPA, verbatim (vendor/ included) - desktop/ — Wails v3 wrapper, updateURL repointed to dtoro/oikos-web releases - compose/ — Dockerfile + Caddyfile, verbatim (the /wails/* 404 and asset no-fallback quirks are load-bearing) - docker-compose.yml — single web service, same 8091:80 publish, mem/cpu limits, and restart policy as the oikos stack's web service - scripts/deploy.sh — mirrors oikos deploy essentials: CI-green gate, TOCTOU guard, version-tagged oikos-web:v$VERSION, prune to 3 - cmd/webhook + scripts/install-webhook.sh — standalone push-to-deploy receiver on :9798 (env-only secrets, no Infisical dependency) - CI: the web job from oikos's ci.yml + the desktop build/release workflow, path-adjusted Own VERSION (0.33.0) with the same bump-on-main rule; starts above oikos's 0.32.x so the desktop updater sees an upgrade.
113 lines
3.5 KiB
Markdown
113 lines
3.5 KiB
Markdown
# Orby — quick start
|
||
|
||
**A procedural glyph engine by Joan Sterjo.**
|
||
|
||
The download kit is self-contained. Start with the path that matches how you
|
||
want to use the engine; no registry download or third-party runtime dependency
|
||
is required.
|
||
|
||
## 1. Open the standalone Studio
|
||
|
||
Open `joan-engine-v5.standalone.html` in a modern browser. It contains the
|
||
Studio, engine modules, and styles in one file, so it works without a build
|
||
step or local server. Use this path to explore states, tune a recipe, and export
|
||
PNG, SVG, animated SVG, or `.joan.json` output.
|
||
|
||
## 2. Import the native ES modules
|
||
|
||
Serve the extracted folder from a local HTTP server:
|
||
|
||
```sh
|
||
cd joan-procedural-glyph-engine-5.0.0
|
||
python3 -m http.server 4173
|
||
```
|
||
|
||
Then import the engine directly from the included source:
|
||
|
||
```html
|
||
<canvas id="ai-glyph" width="160" height="160"></canvas>
|
||
<script type="module">
|
||
import { createGlyph } from "./src/joan-engine.js";
|
||
|
||
const glyph = createGlyph("#ai-glyph", {
|
||
sprite: "ai.idle",
|
||
seed: "product-session",
|
||
gridSize: 68,
|
||
});
|
||
|
||
await glyph.transitionTo("ai.thinking");
|
||
await glyph.transitionTo("status.success", {
|
||
transition: "path-draw",
|
||
});
|
||
</script>
|
||
```
|
||
|
||
Open `examples/canvas.html` for a complete interactive version.
|
||
|
||
## 3. Install the extracted folder locally
|
||
|
||
From an application beside the extracted kit:
|
||
|
||
```sh
|
||
npm install ./joan-procedural-glyph-engine-5.0.0
|
||
```
|
||
|
||
Use the package and its TypeScript declarations through the included exports:
|
||
|
||
```js
|
||
import { createGlyph } from "@joan/procedural-glyph-engine";
|
||
import { playStateSequence } from
|
||
"@joan/procedural-glyph-engine/state-sequence";
|
||
|
||
const glyph = createGlyph("#ai-glyph", {
|
||
sprite: "ai.ambient-idle",
|
||
seed: "conversation-42",
|
||
gridSize: 68,
|
||
});
|
||
|
||
const playback = playStateSequence(glyph, [
|
||
{ sprite: "ai.ambient-idle", holdMs: 5_000 },
|
||
{ sprite: "ai.progress", transition: "contour-trace" },
|
||
{ sprite: "status.success", transition: "path-draw" },
|
||
]);
|
||
|
||
await playback.finished;
|
||
```
|
||
|
||
## Web component
|
||
|
||
Import `src/web-component-register.js`, then use `<joan-glyph>` anywhere in the
|
||
page. Its intrinsic default is 68 × 68 CSS pixels.
|
||
|
||
```html
|
||
<script type="module" src="./src/web-component-register.js"></script>
|
||
<joan-glyph sprite="ai.thinking" seed="conversation-42"></joan-glyph>
|
||
```
|
||
|
||
Open `examples/web-component.html` for a runnable example.
|
||
|
||
## Runtime essentials
|
||
|
||
- `glyph.transitionTo(sprite, options)` performs and awaits a visual handoff.
|
||
- `glyph.setSprite(sprite)` changes state immediately and remains chainable.
|
||
- `glyph.setOptions(patch)` updates the live engine safely.
|
||
- `glyph.signal(type, payload)` injects short-lived product input.
|
||
- `glyph.exportConfig()` returns a JSON-safe recipe.
|
||
- `glyph.toSVG()` and `glyph.downloadPNG()` create portable output.
|
||
- `glyph.destroy()` releases animation frames, observers, and listeners.
|
||
|
||
See `README.md` for the complete state catalog, configuration surface, API,
|
||
events, custom fields and glyphs, orchestration, exports, performance guidance,
|
||
accessibility, and testing.
|
||
|
||
## Verify the kit
|
||
|
||
`SHA256SUMS.txt` lists every payload file included in the archive. The website also
|
||
publishes a checksum beside the ZIP so the archive itself can be verified
|
||
before extraction.
|
||
|
||
Orby is source-available under the Apache License 2.0 subject to the Commons
|
||
Clause License Condition v1.0. You may use, copy, modify, and redistribute it,
|
||
but may not sell Orby or a product or service whose value derives entirely or
|
||
substantially from Orby's functionality. See `LICENSE` and `NOTICE` in the kit.
|