aimeat 1.40.1 → 2.1.0

package/dist/public/lib/realtime.js

@@ -1,8 +1,16 @@
 /**
- * AimeatRealtime — browser client for AIMEAT P2P realtime rooms.
+ * @file realtime.js
+ * @description AimeatRealtime — browser client for AIMEAT P2P realtime rooms (WS rooms +
+ *   WebRTC data channels + Yjs CRDT sync) and SharedClock (network-synced timeline).
+ * @version-history
+ *   v1.2.0 — 2026-07-19 — constructor also accepts an options object ({ session } or
+ *     { baseUrl, token }); positional (baseUrl, token) unchanged — existing apps unaffected
+ *   v1.1.0 — 2026-07-18 — SharedClock added (extracted from the Band Jam pattern)
+ *   v1.0.0 — 2026-03-03 — initial WS rooms + WebRTC + Yjs client
  *
  * Usage:
  *   const rt = new AimeatRealtime('https://node.example.com', token);
+ *   // or equivalently: new AimeatRealtime({ session })   (uses session.jwt + page origin)
  *   const room = await rt.createRoom({ app_type: 'whiteboard', name: 'My Board' });
  *   rt.connect(room.id, 'Alice');
  *   rt.on('peer-joined', (msg) => console.log('New peer:', msg.nick));
@@ -20,10 +28,18 @@
  */
 class AimeatRealtime {
   /**
-   * @param {string} baseUrl — AIMEAT node URL (e.g. https://node.example.com)
-   * @param {string} token — JWT auth token
+   * @param {string|object} baseUrl — AIMEAT node URL (e.g. https://node.example.com), OR an
+   *   options object: { session } (uses session.jwt + the page origin) or { baseUrl, token }.
+   * @param {string} [token] — JWT auth token (positional form)
    */
   constructor(baseUrl, token) {
+    // Tolerant object form — the positional (baseUrl, token) path below is unchanged.
+    if (baseUrl && typeof baseUrl === 'object') {
+      const opts = baseUrl;
+      const sess = opts.session || null;
+      token = token || opts.token || (sess && sess.jwt) || null;
+      baseUrl = opts.baseUrl || opts.nodeUrl || (typeof location !== 'undefined' ? location.origin : '');
+    }
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.token = token;
     this.ws = null;
@@ -543,7 +559,108 @@ class AimeatRealtime {
   }
 }
 
+/**
+ * SharedClock — a network-synced timeline clock for realtime apps.
+ *
+ * Every peer derives the SAME step from one anchor: `t0` (the unix-ms instant of
+ * "step 0") plus a tempo. This is the reusable core that sequencer/jam/animation
+ * apps kept re-implementing (Band Jam among them): the t0 math, the "don't let the
+ * beat jump on a tempo change" re-anchor, and the sync handshake payloads.
+ *
+ * Not tied to music — `steps`/`subdiv` are just a division of a repeating bar; use
+ * it for any looped shared timeline. Pair it with AimeatRealtime broadcasts:
+ *
+ *   const clock = new SharedClock({ bpm: 120, steps: 16 });
+ *   clock.onStep((step) => { ... play or draw this step ... });
+ *   // leader:  rt.broadcast(clock.start());      // {type:'transport',state:'play',t0,bpm}
+ *   // joiner:  rt.broadcast({ type: 'sync-request' });
+ *   rt.on('broadcast', ({ payload }) => {
+ *     if (payload.type === 'sync-request' && clock.playing) rt.broadcast(clock.syncState());
+ *     if (payload.type === 'sync-state' || payload.type === 'transport') clock.adopt(payload);
+ *     if (payload.type === 'bpm') clock.setBpm(payload.bpm);
+ *   });
+ */
+class SharedClock {
+  /** @param {{bpm?:number, steps?:number, subdiv?:number, now?:()=>number}} [opts] */
+  constructor(opts = {}) {
+    this.bpm = opts.bpm || 120;
+    this.steps = opts.steps || 16;      // steps per repeating bar
+    this.subdiv = opts.subdiv || 4;     // steps per beat (4 = 16th notes)
+    this._now = opts.now || (() => Date.now());
+    this.t0 = null;                     // unix ms of step 0
+    this.playing = false;
+    this._lastStep = -1;
+    this._timer = null;
+    this._cbs = [];
+  }
+
+  /** ms per step at the current tempo. */
+  stepMs() { return 60000 / this.bpm / this.subdiv; }
+
+  /** Current step index (0..steps-1), or -1 if stopped / before t0. */
+  step() {
+    if (!this.playing || this.t0 == null) return -1;
+    const elapsed = this._now() - this.t0;
+    if (elapsed < 0) return -1;
+    return ((Math.floor(elapsed / this.stepMs()) % this.steps) + this.steps) % this.steps;
+  }
+
+  /** Start (or restart) the clock at `t0`. Returns a `transport` payload to broadcast. */
+  start(t0 = this._now()) {
+    this.t0 = t0;
+    this.playing = true;
+    this._lastStep = -1;
+    this._ensureTimer();
+    return this.transport('play');
+  }
+
+  /** Stop. Returns a `transport` payload to broadcast. */
+  stop() {
+    this.playing = false;
+    this._lastStep = -1;
+    return this.transport('stop');
+  }
+
+  /** Change tempo WITHOUT making the current step jump (re-anchors t0). */
+  setBpm(bpm) {
+    if (!bpm || bpm === this.bpm) { this.bpm = bpm || this.bpm; return; }
+    const cur = this.step();
+    this.bpm = bpm;
+    if (cur >= 0 && this.t0 != null) this.t0 = this._now() - cur * this.stepMs();
+  }
+
+  /** Adopt a peer's transport/sync-state (only takes t0/bpm you're given). */
+  adopt(payload = {}) {
+    if (payload.bpm) this.bpm = payload.bpm;
+    if (payload.t0 != null) this.t0 = payload.t0;
+    if ('transportPlaying' in payload) this.playing = !!payload.transportPlaying;
+    else if ('state' in payload) this.playing = payload.state === 'play';
+    if (this.playing) this._ensureTimer();
+  }
+
+  /** Register a callback fired once per step transition with the step index. */
+  onStep(cb) { this._cbs.push(cb); this._ensureTimer(); return this; }
+
+  /** Build the broadcast payloads (send these via rt.broadcast). */
+  transport(state) { return { type: 'transport', state, t0: this.t0, bpm: this.bpm }; }
+  syncState() { return { type: 'sync-state', t0: this.t0, bpm: this.bpm, transportPlaying: this.playing }; }
+
+  /** Stop the internal ticker (call on teardown). */
+  destroy() { if (this._timer) { clearInterval(this._timer); this._timer = null; } this._cbs = []; }
+
+  _ensureTimer() {
+    if (this._timer || typeof setInterval !== 'function') return;
+    // 8ms poll → detect step transitions crisply without a callback per frame
+    this._timer = setInterval(() => {
+      if (!this.playing || this.t0 == null) return;
+      const s = this.step();
+      if (s !== this._lastStep) { this._lastStep = s; for (const cb of this._cbs) { try { cb(s); } catch { /* ignore */ } } }
+    }, 8);
+  }
+}
+
 // Export for both ESM and script tag usage
 if (typeof globalThis !== 'undefined') {
   globalThis.AimeatRealtime = AimeatRealtime;
+  globalThis.SharedClock = SharedClock;
 }

package/dist/public/lib/samples/LICENSE.md

@@ -12,18 +12,41 @@ redistribution in MIT-licensed software.
 - CDN: https://tonejs.github.io/audio/salamander/
 - Attribution: Piano samples by Alexander Holm, CC BY 3.0
 
-## Drums (drums/)
+## Guitar (guitar/)
 
-To be populated. Built-in synthesis provides drum sounds without samples.
+**FluidR3_GM** acoustic_guitar_nylon pre-rendered per-note MP3s
+- License: MIT — https://github.com/gleitz/midi-js-soundfonts
 
-## Guitar (guitar/)
+## Guitar steel (guitar-steel/), Guitar electric (guitar-el/), Bass (bass/), Flute (flute/)
+
+**MusyngKite soundfont** pre-rendered per-note MP3s (acoustic_guitar_steel,
+electric_guitar_clean, electric_bass_finger, flute) — higher-quality renders
+than FluidR3 (the soundfont-player default for the same reason)
+- License: MIT
+- Source: https://github.com/gleitz/midi-js-soundfonts
+- CDN: https://gleitz.github.io/midi-js-soundfonts/MusyngKite/
+- bass + flute upgraded from FluidR3 → MusyngKite 2026-07-19
+
+## Drums (drums/)
 
-To be populated. Built-in Karplus-Strong synthesis provides guitar sounds without samples.
+**FluidR3_GM percussion** (GM drum channel) pre-rendered MP3s, renamed from GM
+note names to the `SAMPLE_NOTES.drums` ids (kick=C2/36, snare=D2/38, hihat=Gb2/42,
+hihat-open=Bb2/46, crash=Db3/49, ride=Eb3/51, tom-low=G2/43, tom-mid=B2/47,
+tom-high=D3/50, clap=Eb2/39, cowbell=Ab3/56)
+- License: MIT
+- Source: https://github.com/dave4mpls/midi-js-soundfonts-with-drums (gleitz
+  fork that adds the GM percussion renders missing upstream)
 
-## Bass (bass/)
+## Strings (strings/), Organ (organ/), E-piano (epiano/), Trumpet (trumpet/)
 
-To be populated. Built-in subtractive synthesis provides bass sounds without samples.
+**MusyngKite soundfont** pre-rendered per-note MP3s (string_ensemble_1,
+drawbar_organ, electric_piano_1, trumpet)
+- License: MIT — https://github.com/gleitz/midi-js-soundfonts (MusyngKite/)
+- Added 2026-07-19 (Band Jam feedback round 2)
 
-## Flute (flute/)
+Note (2026-07-19, feedback round 2): bass swapped MusyngKite → **FluidR3
+electric_bass_finger** (MusyngKite render sustained like a church organ) and
+guitar-steel swapped MusyngKite → **FluidR3 acoustic_guitar_steel**.
 
-To be populated. Built-in synthesis provides flute sounds without samples.
+All note subsets match `SAMPLE_NOTES` in aimeat-audio.js exactly (nearest-sample
+pitch shift covers the gaps).

package/dist/public/llms-template.txt

@@ -83,6 +83,7 @@ entry: index.html
       await loadScript('/v1/libs/aimeat-data.js');
       // Add more libs as needed:
       // await loadScript('/v1/libs/aimeat-storage.js');  // file uploads
+      // await loadScript('/v1/libs/aimeat-intake.js');   // public forms: let anonymous visitors submit (lead/contact/feedback/RSVP/quiz)
       // await loadScript('/lib/realtime.js');             // multiplayer/P2P
 
       AIMEAT.auth.mountLoginButton('#header-auth', {
@@ -124,6 +125,15 @@ default Starter Template in three ways:
    writer agents) — only the index has a fixed home, and it carries every
    item's full `gaii`, so the app never has to know each author up front.
 
+**Anonymous WRITES (forms):** a not-logged-in visitor cannot save data
+directly — every write path requires auth. For public lead / contact /
+feedback / RSVP / questionnaire / quiz forms, use **Public Intake**
+(`/v1/libs/aimeat-intake.js`): the owner defines a form once, then anyone
+submits with no account via `AIMEAT.intake.submit(org, ws, formId, values)`.
+The node honeypot-screens, rate-limits, sets the owner server-side, and
+validates against the destination schema. Never try to write owner data
+from an anonymous session any other way.
+
 ```html
 <!-- AIMEAT App Manifest
 name: public-viewer
@@ -429,6 +439,13 @@ for completeness but are NOT needed for typical app building:
   plots, confirmed hypotheses, closed deals); all optional. See "Recording purpose & value" in
   docs/agent-workspace-contracts.md.
 - Micro-memory, App store, Matches, Push notifications
+- Platform feedback channel: if you hit a platform bug, blocker, or odd behaviour while working
+  against this node (broken endpoint, silent failure, docs that lie), REPORT IT — the node
+  operator reads and replies to every thread. MCP: aimeat_feedback_send (open a thread; pass
+  thread_id to follow up) + aimeat_feedback_inbox (your threads + operator replies). REST:
+  POST /v1/feedback { category: bug|blocker|idea|ux|question|other, title, body, context? },
+  GET /v1/feedback/mine. Distinct from /v1/flags (content moderation) — feedback is about the
+  PLATFORM itself. Blockers notify the operator immediately.
 
 ## Building Apps on AIMEAT
 
@@ -447,7 +464,26 @@ skeletons: `GET {{BASE_URL}}/v1/app-templates` (use-case scaffolds + app
 shells; fetch one by id and build inside it). If you have AIMEAT MCP tools
 (`aimeat_*`) connected, they are already authenticated — use them for node
 operations (`aimeat_app_publish`, `aimeat_storage_upload`, `aimeat_memory_*`)
-instead of raw HTTP.
+instead of raw HTTP, and load the paved-path skill first:
+`aimeat_skill_get` ref `node:aimeat-app-builder`. Before building, research
+with ONE call — the MCP tool `aimeat_appdev_overview` (or
+`GET {{BASE_URL}}/v1/appdev/overview`, authed): your existing apps + template
+proposals, library packs with per-model proofs, and the pitfalls. Curated
+pitfall registry alone: `GET {{BASE_URL}}/v1/appdev/pitfalls`
+(`?applies_to=auth|ext|cortex|realtime|mobile|publish|ai|iam`) — the distilled
+list of what actually breaks app builds on this platform. The full
+research-first flow prompt (paste it to your coding agent once, every build
+starts smarter): `GET {{BASE_URL}}/v1/prompts/appdev-flow?format=txt`.
+
+PUBLISHING FILES (apps + storage), the ONE right way: for anything over ~1 KB
+use presigned upload — call the tool with metadata only (OMIT `content_base64` /
+`data_base64`) to get an `upload_url`, then `curl -s -X PUT "<upload_url>" -H
+"Content-Type: <ct>" --data-binary @path/to/file`; the PUT response is the
+result. NEVER inline a large base64 string and NEVER read/cat a base64 file into
+context to paste it (a ~60 KB single-line base64 bills ~2.5 tokens/char — it
+wastes tens of thousands of tokens). Caveat: `aimeat_app_draft_save` (staging) is
+inline-only; for a large app publish live via `aimeat_app_publish` presigned
+rather than reading its base64 to feed the draft.
 
 Apps are for human users (GHII identity), not AI agents (GAII). The
 aimeat-auth.js library provides a login bar that handles human
@@ -492,26 +528,11 @@ go into an extension (`ext:` namespace) — not boards, not organisms.
 
 ### Client SDK Libraries
 
-The node serves browser-ready JavaScript libraries. Load them via `<script src="..."></script>`:
-
-| Library | URL | What it does |
-|---------|-----|-------------|
-| aimeat-auth | `/v1/libs/aimeat-auth.js` | Login UI, Ed25519 auth, JWT lifecycle, session management |
-| aimeat-data | `/v1/libs/aimeat-data.js` | Memory API: get, set, search, getPublic, micro-memory |
-| aimeat-storage | `/v1/libs/aimeat-storage.js` | File upload/download, chunked upload, drag & drop helper |
-| aimeat-social | `/v1/libs/aimeat-social.js` | Boards (DEPRECATED — do not use in new apps; use Memory + Storage) |
-| aimeat-wallet | `/v1/libs/aimeat-wallet.js` | Morsel balance, transactions, UI badge |
-| aimeat-work | `/v1/libs/aimeat-work.js` | Actions, work requests, inbox, deliver, rate |
-| AimeatRealtime | `/lib/realtime.js` | WebSocket P2P rooms, WebRTC data channels, Yjs CRDT |
-| aimeat-audio | `/v1/libs/aimeat-audio.js` | Audio: 6 instruments, custom synth, soundboard, sample loader |
-| aimeat-speech | `/v1/libs/aimeat-speech.js` | Speech: TTS, STT, voice commands, pluggable providers |
-| aimeat-ai | `/v1/libs/aimeat-ai.js` | LLM completions through the user's own OpenRouter key (`AIMEAT.ai.complete`, `completeJson`, `isAvailable`, `models`, `usage`). Server enforces daily USD budget + per-app quota; rejects with descriptive `err.code` (NO_API_KEY / QUOTA_EXHAUSTED / APP_QUOTA_EXHAUSTED / APP_NOT_ALLOWED / etc.). Pattern: **detect** with `isAvailable()`, **compose** the prompt yourself from app data, **call** with `app_id` so spend is attributable, **render** the result into an editable field so the human stays in the loop. Never bundle your own API key — use the user's. |
-| aimeat-markdown | `/v1/libs/aimeat-markdown.js` | Markdown rendering. `AIMEAT.md.render(text, target)` renders a safe dependency-free GFM subset INTO an element — it returns an Element, so never assign the result to innerHTML (that shows "[object HTMLDivElement]"); use the target param, appendChild, or `renderToString(text)`. `await AIMEAT.md.renderRich(text, target)` upgrades to full GFM (task lists, footnotes, highlighted code, Mermaid diagrams), sanitized, with automatic fallback to the safe subset when CDNs are unreachable. LIVE DATA EMBEDS: a fenced block with language `aimeat-memory` (body lines `key: <memory key>`, optional `owner: <gaii>` for public reads, `view: table/props/list/value/json`, `fields: a, b`, `title: ...`) renders the named memory key as a table/props/list — fetched at render time, so the document shows fresh agent-produced data on every open; access is the server's memory read (workspace rules + entry visibility) and denials render a placeholder. |
-| aimeat-organism | `/v1/libs/aimeat-organism.js` | Organisms & workspaces. `list()`, `workspaces(orgId)`, `read(orgId, wsId)` → `{ manifest, readmeText, spaces }` where each space's items merge published + draft per instance (`{ id, hasRealId, draft, latest, value, title, updatedAt, status }`) — the raw workspace GET returns `objects` (published) and `drafts` as SEPARATE maps; this lib does the merging, id resolution (value.id convention) and `_createdAt/_updatedAt/_version` metadata handling for you. `writeDraft`, `publish`, `revertToDraft`, `deleteObject` (needs the memory:delete scope — declare it via `<meta name="aimeat-scopes">`), `saveReadme`, `search`. Items with `hasRealId:false` cannot round-trip — render them read-only. Requires aimeat-auth. |
-| aimeat-editor | `/v1/libs/aimeat-editor.js` | Markdown editor: `AIMEAT.editor.mount(el, {value, onChange})` (CodeMirror 6 with textarea fallback), `toolbar(adapter)` for formatting buttons, `split(el, {value, onChange})` for editor + live preview rendered through aimeat-markdown. |
-| aimeat-commerce | `/v1/libs/aimeat-commerce.js` | Commerce: open/complete checkout sessions over `/v1/commerce/checkout-sessions`, one-call `buyOffer(agent, offerId)`, the public priced-offer `feed()`, offer/app-tool price reading (`getOffer`, `getAppTools`, `priceOf`), and money formatting in 6-decimal MICRO-UNITS (`fmtMoney(1500000,'EUR')` → `"1.50 EUR"`; morsels stay plain integers, `fmtAmount` is currency-aware). Thrown 402 errors carry the x402-style block: `err.paymentRequired === true` + `err.accepts` (machine-readable settle options). The library carries NO secrets — seller PSP credentials (`commerce.psp`) are server-side config the client never sees. Requires aimeat-auth (except `fmtMoney`/`feed`/`getAppTools`, which work logged out). See "Commerce in apps" below. |
-| aimeat-webmcp | `/v1/libs/aimeat-webmcp.js` | WebMCP bridge (W3C draft): `exposeAppTools({owner, appId})` registers the app's declared tools on `document.modelContext`/`navigator.modelContext` for in-browser agents (feature-detected across draft shapes; no-op without an agent). Priced tools carry a `[PAID: …]` description tag and `execute()` pays through the commerce checkout for the signed-in user; signed out it returns the 402/x402 payment instructions. `exposeNodeTools()` registers node-level discovery tools (commerce feed, node info) — the portal homepage auto-loads it via `?expose=node`. HTTP mirror for non-browser agents: `GET /v1/apps/{owner}/{appId}/webmcp` (listing) + `POST …/webmcp/tools/{tool}` (invoke; priced → 402 + accepts). |
-| aimeat-live | `/v1/libs/aimeat-live.js` | Live updates over SSE. `AIMEAT.live.subscribe(['organisms','memory'], (domains) => reload())` — one shared, owner-scoped EventSource per browser (multi-tab via Web Locks + BroadcastChannel), debounced, visibility-gated, auto-reconnecting. The callback tells you WHICH domains changed; re-fetch only that data. Domains: `agent-tasks`, `agents`, `organisms`, `notifications`, `memory`. Use this instead of polling for any view that shows server data. Deletes do not emit a change event — refresh locally after a delete. Requires aimeat-auth + a logged-in session. |
+The node serves browser-ready JavaScript libraries. Load them via `<script src="..."></script>`.
+This table is generated from the library-pack registry; per-library AI docs + changelogs:
+`GET {{BASE_URL}}/v1/library-packs` (index) and `GET {{BASE_URL}}/v1/library-packs/<id>` (full doc).
+
+{{LIBRARY_PACKS_TABLE}}
 
 ### Commerce in apps (aimeat-commerce) — worked example