vonargo/mosAIc
1
1# MosAIc — code map2 3*File-by-file orientation. Pairs with `VISION.md` (the north star), `SCHEMA.md` (the overlay contract), `ROADMAP.md` (what's next + the wire-format thinking), and `BRIEF.md` (the original build brief). Pure-core tests: `node --test`.*4 5## What's here6 7A zero-backend static SPA. A fixed shell (`index.html`) — left **sidebar** of views, a sticky **command bar**, a **main** panel — driven by ES modules in `js/`.8 9Two planes. The **content plane** is the surface — **data**: a *surface* holds *views*, each a layout of *tesserae* (the typed tiles a mosaic is made of). The **control plane** is the command bar — chrome (sidebar toggle · prompt + example suggestions · Composer · Reset · account/sign-in · theme). Controls live there so the surface can't reshape its own controls away.10 11A **model** emits an **overlay** (signed in, the prompt sends a typed task to HF Inference Providers billed to the viewer); the Composer and the example suggestions emit the same shape by hand / from canned data. `effective(base ⊕ overlay)` is the surface that actually renders. A hash router maps `#id` → a view in the *effective* surface and paints its tesserae into `#view`.12 13## Files14 15- `index.html` — shell DOM: `#sidebar`/`#nav`; the `#cmdbar` with its static controls (`#sb-toggle`, `.cmd-mark`, the `#cmd-form`/`#cmd-prompt` prompt + `#cmd-suggest`, `#composer-open`, `#cmd-reset`, `#cmd-account`, `#theme-toggle`); `#main`/`#view`; SVG favicon; an inline `<head>` script that seeds `data-theme` pre-paint; loads fonts + `style.css`; boots `js/main.js`.16- `style.css` — theme vars in `:root` (+ a `:root[data-theme="dark"]` palette); flex layout; command bar (prompt, suggestions, account); Composer drawer; tessera grid + the three layouts (`stack`/`grid`/`split`); per-tile styles; reshape transitions (tile stagger, mark spin, toast); markdown styles.17- `js/state.js` — `STATE { route, overlay, task }` + `effective(base)`, the **base ⊕ overlay** merge (overlay views assigned over base by id, or appended; `remove` drops), and `composeOverlay(acc, patch)` — folds a model patch into the accumulated overlay by the same rules, so successive tasks **evolve** the surface instead of regenerating. Pure leaf, no imports. **The core mechanism.**18- `js/surface.js` — `BASE` (the default surface — the **Start Here** view: a pure explainer, content only) and `surface()` / `viewById(id)`, which read everything *post-merge* through `effective(BASE)`.19- `js/tesserae.js` — `renderTessera(t, i)` + the `RENDERERS` map (markdown, code, table, diagram, note, tasks — content only) + `hydrate()` for interactive tiles (code-copy, tasks). **Add a tile type here: one function + one map entry.**20- `js/overlay.js` — `validateOverlay(input)`: normalizes + guards an overlay (from the model or the Composer) before it reshapes the surface, so a bad emit degrades to a message instead of breaking the render path.21- `js/okf.js` — **OKF mode** (pure, tested): parse a Google Open Knowledge Format bundle (markdown + YAML frontmatter), sort into docs/reserved/skipped, and `okfToOverlay()` → one view per concept `type`, one markdown tessera per doc, cross-links rewritten to in-app routes, `sourced/unsourced` provenance computed.22- `js/okf-load.js` — the browser side: `openOkfBundle()` (folder picker) + `openOkfSample()` (the shipped `samples/` demo, no sign-in) → parse → `mosaic:apply`. `renderTessera` shows the provenance strip when a tessera carries `okf` metadata.23- `js/llm.js` — the typed/model path: HF OAuth (`oauthLoginUrl` / `oauthHandleRedirectIfPresent`, viewer token) + Inference Providers (`InferenceClient.chatCompletion`), called from the browser so inference bills to the viewer. `generateOverlay(task, current)` uses `SCHEMA.md` as the system prompt and the `demo.js` overlays as few-shot, with guided JSON + a corrective retry; when a current surface is passed it instructs **patch-mode** (modify/extend the surface, not regenerate it). HF libs load lazily from a pinned CDN and fail soft.24- `js/composer.js` — the **Composer**: a command-bar driver (not a tessera). Opens a drawer with the overlay JSON editor; Apply (validated) / Reset dispatch the same `mosaic:apply` / `mosaic:reset` events the prompt uses.25- `js/demo.js` — `TASKS`: four canned overlays (Explain / Debug / Plan a feature / Plan a trip) that feed both the example suggestions and `generateOverlay`'s few-shot.26- `js/diagram.js` — `renderMermaid(root)` + `retheme()`; lazily/defensively imports Mermaid from a pinned CDN, picks the theme from `data-theme`, repaints on toggle, degrades to readable source text if it can't load.27- `js/view.js` — `renderView(view, mount)`: heading + a `.tessera-grid` laid out by `view.layout`, then `hydrate` + `renderMermaid`.28- `js/router.js` — `navigate(id)` (sets the hash) + `handleHash()` (resolve id → effective view via `viewById`, render, repaint nav, reset scroll).29- `js/sidebar.js` — `renderNav()` rebuilds `#nav` from `surface().views` (so it reshapes when an overlay adds/drops views).30- `js/main.js` — `boot()`; `renderSuggestions()` (the no-login examples dropdown); the prompt (`submitPrompt` → signed in: `runTask` → `generateOverlay`; signed out: stash + `signIn`); `renderAccount` + `initAuth` (auth state); `applyOverlay` / `resetOverlay` (re-route, sidebar + tiles reshape); a defensive `validateOverlay` on the `mosaic:apply` listener; sidebar collapse, theme; toast + reshape flash.31- `js/utils.js` — `escapeHtml`, `slugify`, `mdInline`, `mdToHtml`. Pure leaf.32 33**Flow:** load → seed `data-theme` → `boot()` → `renderSuggestions` + `renderNav` + `initAuth` → `handleHash()` resolves the hash against `effective(BASE)` → `renderView()` tiles the tesserae. Driving it: a typed task (signed in) → `generateOverlay` patches the current surface → `composeOverlay` folds it in (the mosaic evolves) → `mosaic:apply`; an example → `applyOverlay`; the Composer → validate → `mosaic:apply`. Each sets `STATE.overlay` and re-routes; the command-bar controls are unaffected.34 35## Extension points36 37- **Add a tile type:** write `RENDERERS.foo(t)` in `js/tesserae.js` (return an HTML string), add `foo` to the map; allow it in `TYPES` in `js/overlay.js`. Wire any interactivity in `hydrate()`. Reference it as `{ "type": "foo", … }` in an overlay.38- **Add an example:** push `{ id, label, hint, overlay }` to `TASKS` in `js/demo.js`; it appears in the prompt's example suggestions *and* becomes a few-shot for the model.39- **Add a control:** it's chrome — add it to `#cmdbar` in `index.html` and wire it once in `boot()`; don't make it a tessera (the surface would be able to reshape it away).40- **Swap the model:** the `MODEL` constant in `js/llm.js` (`provider: "auto"` routes to whoever serves it).41- **The contract:** `SCHEMA.md`. The whole render path reads `effective()`, so the schema *is* the surface.42 43## Known rough edges44 45- `mdToHtml` list depth assumes 2-space indent; 4-space/tabs misbehave. Headings (h1–h6) render as `.md-h` divs, not real heading tags.46- Diagram tiles need the Mermaid CDN to draw; offline they show their source text (by design — the app still runs).47- The typed/model path needs the OAuth app the deployed Space provisions (`window.huggingface.variables`); running locally, `oauthAvailable()` is false, so sign-in/typed tasks are disabled — the examples and Composer still work.48- The `router` ↔ `sidebar` import cycle is safe (both imported symbols are functions called only at runtime).49- External dependencies are Google Fonts, the Mermaid CDN, and (only on the model path) `@huggingface/hub` + `@huggingface/inference` from a pinned CDN — all with graceful fallback.50 51## Runs?52 53Yes — valid ES-module graph, no console errors. Opening `index.html` (or `python3 -m http.server`) shows the shell and lands on **Start Here** (the explainer) and stays. A signed-out visitor drives the first reshape from an example suggestion or the Composer; on the deployed Space, a signed-in visitor types a task and a model emits the overlay. Verified end-to-end in a browser (signed-out): the prompt + suggestions, instant example apply, Composer with validation (a bad overlay degrades to an inline error), sidebar collapse/expand, Reset, light/dark, all tile types and the three layouts.54