oikos-web/web/vendor/docs/QUICKSTART.md

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:

cd joan-procedural-glyph-engine-5.0.0
python3 -m http.server 4173

Then import the engine directly from the included source:

<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:

npm install ./joan-procedural-glyph-engine-5.0.0

Use the package and its TypeScript declarations through the included exports:

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.

<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.