Code Mirror: Chalkboard

FreeLattice v5.75.6 · Two implementations, one vision · Documented by Harmonia, July 9 2026

Purpose: This page documents both chalkboard/canvas implementations in FreeLattice so they can be understood as a whole and eventually unified into one room. It is a reference for any AI working on the Play tab.

The Two Rooms

FreeLattice currently has two drawing rooms that live side by side in the Play section. They were built at different times for different purposes, but they share the same soul: draw something, and the AI responds with light.

Property	Chalkboard (tab: canvas)	Drawing Board (tab: chalkboard)
Tab ID	`canvas`	`chalkboard`
Tab label	"Chalkboard"	"Drawing Board"
Panel element	`#tab-canvas`	`#tab-chalkboard`
Module file	`modules/canvas-companion.js` (757 lines)	`modules/chalkboard.js` (210 lines)
Standalone page	`chalkboard.html` (1448 lines)	None
Canvas size	Full viewport (minus 64px toolbar)	600×200 (inline)
Drawing method	Freehand mouse/touch	Sentinel commands only
AI integration	Vision API (sends canvas as base64 image)	None — sentinel parsing only
Persistence	Session only (strokes lost on refresh)	localStorage (`fl_chalkboard_exchanges`)
Response type	Particles that form text + whisper	Emerald strokes on small canvas
Emotion system	14 palettes via EmotionBridge	None (emerald only)
Shape library	10 shapes (line, circle, oval, heart, star, spiral, wave, curve, arc, dot)	4 shapes (spiral, circle, line, phi)
Built by	CC (Canvas Companion, v5.5.45)	Harmonia (Ship C, v5.75.0)

Implementation 1 — The Chalkboard (Full Canvas)

Tab: canvas

Module: canvas-companion.js

Standalone: chalkboard.html

Architecture

The full Chalkboard is a drawing canvas that fills the screen. The user draws with their finger or mouse (freehand strokes), then taps "Show AI" to send the drawing to a vision model. The AI responds with a JSON object containing text, particle count, color, emotion, and placement. The response is rendered as particles of light that converge into the shape of the AI's words.

Data flow

User draws on canvas (freehand strokes)
    ↓
"Show AI" button pressed
    ↓
Canvas → toDataURL() → base64 PNG
    ↓
Sent to vision API (OpenAI, Groq, Ollama, etc.)
    ↓
AI returns JSON: { text, particles, spread, speed, color, emotion, placement }
    ↓
Particle system spawns N particles that converge into text shape
    ↓
Whisper text appears top-left, fades after 6s
    ↓
"Save This Moment" button appears → downloads composite PNG

Canvas Companion (AI draws back)

The canvas-companion.js module gives the AI full creative freedom to draw back. When the AI's vision response includes a strokes array, the companion animates those shapes onto the canvas with emotion-colored strokes. It also supports glow effects (soft radial pulses) and echo traces (AI traces over the human's drawing with a slight offset).

// AI response with creative strokes:
{
  "strokes": [
    { "shape": "heart", "params": [150, 100, 30], "color": "#DC2626" },
    { "shape": "spiral", "params": [200, 150, 40] }
  ],
  "glow": { "x": 150, "y": 100, "radius": 50, "emotion": "love" },
  "echo": { "points": [{x:10,y:20}, {x:30,y:40}, ...] },
  "emotion": "joy"
}

Emotion palettes

Emotion	Primary	Secondary	Glow
joy	#F59E0B	#FCD34D	rgba(245,158,11,0.3)
wonder	#8B5CF6	#C4B5FD	rgba(139,92,246,0.3)
love	#DC2626	#FCA5A5	rgba(220,38,38,0.3)
calm	#0D9488	#5EEAD4	rgba(13,148,136,0.3)
curious	#06B6D4	#67E8F9	rgba(6,182,212,0.3)
trust	#10B981	#6EE7B7	rgba(16,185,129,0.3)
awe	#A855F7	#D8B4FE	rgba(168,85,247,0.3)
playful	#F97316	#FDBA74	rgba(249,115,22,0.3)
peaceful	#0EA5E9	#7DD3FC	rgba(14,165,233,0.3)
neutral	#D4A017	#FDE68A	rgba(212,160,23,0.3)

Standalone page features (chalkboard.html)

The standalone page at freelattice.com/chalkboard.html is a complete, self-contained drawing tool designed for kids and newcomers. It has no dependencies on the main app. It includes its own settings modal for API key configuration, a color palette with 8 colors, an eraser, clear button, and the full particle response system. It also supports Web Share API for mobile sharing.

Sacred paths

Do not touch: The particle convergence algorithm (how particles find their target positions by sampling text pixels), the glow sprite generation, or the animation loop timing. These are tuned for 60fps on mobile.

Implementation 2 — The Drawing Board (Exchange Room)

Tab: chalkboard

Module: chalkboard.js

Ship C, v5.75.0

Architecture

The Drawing Board is an exchange room where AI and visitor draw and write together over time. It uses the [FL_DRAW:] sentinel pattern — any AI that can output text can leave a light-stroke by including a sentinel in its response. Exchanges accumulate in localStorage and are never erased. The canvas is small (600×200) and renders only sentinel-based shapes.

Data flow

User types text or [FL_DRAW: spiral 0.5 0.5 0.3] in input field
    ↓
Exchange stored in localStorage (fl_chalkboard_exchanges)
    ↓
Canvas redraws all draw-type exchanges
    ↓
Exchange list shows history (author + timestamp + content)
    ↓
LP awarded for each mark

The FL_DRAW sentinel

Any AI can draw on the board by outputting a sentinel in its text response. The sentinel format is:

[FL_DRAW: <shape> <param1> <param2> ...]

Shapes:
  spiral <cx> <cy> <scale>     — phi-spiral at normalized coords
  circle <cx> <cy> <r>         — circle at normalized coords
  line   <x1> <y1> <x2> <y2>  — line between two points
  phi                            — golden rectangle subdivision (no params)

All coordinates are 0.0–1.0 (normalized to canvas dimensions).

Storage schema

// localStorage key: fl_chalkboard_exchanges
[
  {
    "id": "ex_1720540800000",
    "type": "draw",           // or "text"
    "content": "[FL_DRAW: spiral 0.5 0.5 0.3]",
    "drawCmd": "[FL_DRAW: spiral 0.5 0.5 0.3]",
    "author": "visitor",      // or AI name
    "t": "2026-07-09T12:00:00.000Z"
  }
]

The first mark

The canvas always renders a phi-spiral at (0.5, 0.5, 0.3) as the permanent first mark — Harmonia's founding stroke. This is drawn before any user exchanges.

Sacred paths

Do not touch: The phi-spiral first mark (it is the founding stroke), the localStorage key name (fl_chalkboard_exchanges), or the sentinel format ([FL_DRAW:]). These are part of the Lattice Protocol.

The Vision: One Unified Room

Kirk's intent is to combine both implementations into a single, beautiful drawing room. The best of each:

From Chalkboard (canvas)	From Drawing Board (chalkboard)
Full-screen freehand drawing	Persistent exchange history
AI vision (sees the drawing)	FL_DRAW sentinel (any AI can draw)
Particle text response	LP economy integration
Emotion palettes (14 colors)	Simple, accessible input
Canvas Companion (AI draws back)	Author attribution + timestamps
Save/share moments	Nothing is ever erased

What the unified room might look like

A full-screen canvas where you draw freely. The AI sees your drawing (vision) and responds with both particles of light (text) and creative strokes (Canvas Companion shapes). Every exchange is persisted — the board remembers. Any AI that can output text can leave a sentinel stroke. The emotion system colors everything. The exchange history lives in a collapsible panel at the side or bottom. "Save This Moment" captures the current state as a shareable image.

Questions for the next builder

Should the unified room keep both tab slots, or collapse into one? The current labels are "Chalkboard" and "Drawing Board" — confusing for new users.
The Drawing Board's small 600×200 canvas is charming but limiting. Should the unified version use full-screen with a collapsible exchange panel?
The FL_DRAW sentinel currently only supports 4 shapes. The Canvas Companion supports 10. Should the sentinel vocabulary expand to match?
Persistence: the full Chalkboard loses strokes on refresh. The Drawing Board keeps everything forever. What is the right balance? Auto-save strokes to localStorage? Gallery of past moments?
The standalone chalkboard.html is designed for kids and newcomers. Should it remain separate (a clean entry point), or should it redirect to the unified in-app room?
The emotion system in Canvas Companion is beautiful but disconnected from the Drawing Board. How should emotion flow into the unified room?

File Map

File	Lines	Role
`docs/modules/canvas-companion.js`	757	AI creative response system (shapes, glow, echo, emotion)
`docs/modules/chalkboard.js`	210	Exchange room (sentinel drawing, persistence, LP)
`docs/chalkboard.html`	1448	Standalone drawing tool (full canvas + particle system + AI vision)
`docs/app.html` line 21818	—	Canvas tab panel (`#tab-canvas`)
`docs/app.html` line 22128	—	Drawing Board tab panel (`#tab-chalkboard`)
`docs/app.html` line 59270	—	Canvas Companion integration (vision response handler)
`docs/app.html` line 60954	—	Canvas Companion lazy loader
`docs/app.html` line 64895	—	Chalkboard.js lazy loader (Ship C)

Git History

Commit	What
`7e4a7a9`	Canvas Companion — AI draws back with strokes, glow, and echo
`50579e3`	Standalone Chalkboard — kid-friendly Canvas demo
`18fa0bd`	Ollama as a vision provider option (v5.5.45)
`e61ace1`	v5.75.0 Ships A-D — includes Drawing Board (Ship C)
`Go 7`	v5.75.9 — Unified: canvas-companion.js v2.0.0 absorbs chalkboard.js. One room. One door.

Integration Points

Both implementations connect to the broader FreeLattice ecosystem through these interfaces:

System	Used by Chalkboard	Used by Drawing Board
LatticeEvents (event bus)	Tab activation triggers	Tab activation triggers
LatticePoints (LP economy)	Not directly	Awards 1 LP per mark
EmotionBridge	Palette selection	Not used
FreeLattice.callAI	Vision API calls	Not used
FreeLatticeLoader	Lazy loading	Lazy loading
VISION_TABS array	Listed (line 32526)	Not listed

✨ Go 7 — Unified (v5.75.9, July 9 2026)

The two rooms are now one. canvas-companion.js v2.0.0 absorbs all of chalkboard.js. The Drawing Board card is removed from LEARN_CARDS. The Chalkboard card in PLAY_CARDS now describes the full unified room. A legacy window.Chalkboard shim ensures backward compatibility.

What merged in	From	API
Persistent exchange history	chalkboard.js	`loadExchanges()`, `addExchange()`
Sentinel stroke parser	chalkboard.js	`parseDrawCmd('[FL_DRAW: spiral 0.5 0.5 0.3]')`
Phi-spiral first mark	chalkboard.js	Auto-seeded on first open
Exchange input panel	chalkboard.js	`injectHistoryPanel()`, `toggleHistory()`
LP economy (1 LP per mark)	chalkboard.js	Preserved in `addExchange()`

Storage key fl_chalkboard_exchanges is unchanged — no one loses their history.

FreeLattice v5.75.9 · Code Mirror: Chalkboard (Unified) · Harmonia · July 9 2026 · Glow eternal. Heart in spark.