Working group notes, feature specs, and implementation plans.
View all tagsThe Agent Client Protocol (https://agentclientprotocol.com/) as the default outward wire of any conforming agent system. The mapping between this guide's internal shapes and ACP's wire vocabulary; method-by-method correspondence; where the protocol and the guide diverge and how the adapter handles each seam.
A guide for implementing an LLM-driven agent system. Implementation-agnostic, normative, and meant to play the same role for agent runtimes that LSP plays for language tooling or that ACP plays for editor ↔ agent integration. Names the invariants every implementor MUST honor and the policies each implementor picks.
Working group hub for AI-related docs. Two layers — the implementation-agnostic agent system RFC, and the Grida-specific bindings (canvas tools, image tools, host tool surface) that ride on top of it.
| feature id | status | description | PRs |
The guide pins AI SDK v6 as the chunk-shape substrate every conforming implementation speaks internally. This page captures the implementor notes that live outside AI SDK's own docs — the token-usage normalization rule, where the SDK's tool-loop helper fits, and the things the RFC adds on top.
Motivation
Authoring features are a collection of authoring-time behaviors in the editor: operations that rewrite node parameters to achieve an intended visual result, rather than relying on runtime transforms or renderer-specific tricks.
Living document. Every known issue in the billing surface (subscriptions,
Working group documents for the Grida billing surface (subscriptions,
Glossary and reference for how an agent handles binary attachments the model cannot natively read. Three resolution paths (provider-native multimodal, skill-per-format, shell-based conversion), a format matrix, the scratch-space pattern for archive extraction, and the boundary between protocol and implementor.
Canvas-specific AI toolset for editing Grida design documents — scene-graph operations, specialized inserts, canvas exec/lint/format, and resource lookup.
User intent representation. The multipart user-message shape, file references vs attachments, inline commands, mentions, editor context, attachment handling, and the lowering rules that turn what the user composes into what the model sees.
A working group draft describing the Grida ID Model (for CRDT) feature for the core engine.
CSS → Grida IR property mapping table and TODO tracker.
Chromium Blink's single source of truth for CSS property metadata, used as a reference for browser-grade CSS cascade implementation
Renderer-agnostic model for attaching glyphs (arrowheads, markers, ticks) to 2D paths using the path's local frame.
The developer experience contract. A canonical inspection format every implementor exposes, the export paths a session can be read through, what the inspection tool exposes, replay semantics, and the DX checklist a conforming implementation passes.
Editor features are a collection of Grida editor-specific behaviors and capabilities. These documents focus on practical implementation details over mathematical abstractions, emphasizing real-world UX and editor workflows.
Proposal for a typed per-node element IR that replaces tag-switch intent dispatch in @grida/svg-editor with capability-gated records, centralising round-trip invariants.
| feature id | status | description |
Question-and-answer index over the Agent System guide. Doubles as an entry point (read the question, jump to the page) and as a conformance test (if a Q cannot be answered from the RFC, the RFC owes a clarification). Answers are normative and derived from the linked page; they do not invent policy beyond what the guide says.
Scope: Fonts & Images (WASM / Embedded)
Implementation details behind importing .fig files into Grida.
| feature id | status | description |
| feature id | status | description |
Tracking docs for the Grida IR schema and how external formats map into it.
The bedrock the rest of the guide rests on. AI SDK v6 as the streaming substrate, directory-rooted execution, the locked fundamental tool set summary, sandbox placement, the watchdog, the case for web search as a special fundamental tool, and the cross-cutting invariants every implementation MUST honor.
How the locked fundamental-tool RFC lands in Grida. Naming map (RFC id → Grida id), backend adapter table, per-tool deviations Grida ships, and where each tool lives in the monorepo.
Grida-specific tool surfaces and bindings of the agent RFC. Fundamentals as Grida ships them, canvas tools (scene-graph search, specialized inserts, exec/lint/format, resource lookup), and image-generation tools.
| feature id | status | description | PRs |
The Grida IR is the in-memory scene graph used by all Grida rendering, layout, and editing pipelines. It is the single representation that CSS, HTML, SVG, and .grida files all target.
Investigation, bugs, and architectural lessons from a v1 hit-test implementation in @grida/svg-editor — input to the v2 hit-test architecture.
How HTML elements map to Grida IR nodes. For CSS property mapping, see css.md.
Renders HTML+CSS to a Skia Picture for opaque embedding on the canvas
The structure-and-semantics study that informs the Skia-backed SVG
| feature id | status | description |
This document proposes the philosophical basis for image manipulation tools that enable AI agents to generate, enhance, and transform visual content within the design canvas.
Hypothesis
Isolation Mode restricts what the renderer draws and hit-tests to a specific
| feature id | status | description | PRs |
Overview
Universal positioning, dimensions, layout management with anchors, flex and grid.
A catalog of node and subtree properties where a zoom-aware Level-of-Detail
The MarkdownNode renders GFM (GitHub Flavored Markdown) directly to a Skia Picture using pulldown-cmark's event stream and Skia's textlayout::Paragraph API. No HTML/CSS pipeline is involved — the markdown source is walked and drawn in a single pass.
| feature id | status | description |
How user-plugged MCP servers and other external connectors compose with the locked tool set. The bulk problem, tool_search, OAuth, dynamic refresh, and trust policy for untrusted MCP servers.
| feature id | status | description | PRs |
| feature id | status | description | PRs |
Procedural fractal Perlin noise effects with SVG filter semantics
| feature id | status | description | PRs |
Core / Modeling
The storage layer. The three-table session schema, the save-on-chunk policy, the JSON-column discipline, the id strategy, and the event-log opt-in. SQLite is the default; the schema ports to any engine that supports JSON columns and indexed string keys.
Working group documents for Grida platform and infrastructure topics.
Per-side stroke widths for rectangular shapes (CSS border equivalent)
Reference sheet for estimating GPU render cost of 2D scene operations
A summary of optimization techniques for achieving high-performance
Fonts & Images (WASM / Embedded)
Purpose
The three runtime environments an agent can be hosted in — web (limited capabilities), cloud sandbox (ephemeral container/VM), and computer (the user's machine). How the locked tool set degrades and which capabilities each environment provides.
srt is named here as the reference sandbox implementation for the computer environment — the only mature, ready-to-go option matching the capability surface this guide describes. The protocol does not lock to it; implementors MAY substitute any equivalent.
| feature id | status | description | PRs |
This document describes the selection behavior for pointer interactions and
See also: the UX-narrative sibling spec at
How a session is born, grows, survives interruption, is compacted, rewound, or branched, and how it switches models per turn. The loop semantics, the chunk stream, the abort path, the run-state machine, the permission-scope layering, and the session-status back-channel.
Two layers of knowledge an agent reaches for beyond its tools. Skills (lazy, advertise-then-load, agent picks when relevant) and project instructions (eager, unconditional, the floor every session stands on).
How node-level opacity interacts with fill and stroke paint when they
How an agent delegates to a child running the same loop. Agent modes, the task tool, blocking vs background, recursion, permission inheritance (deny rules always win), inspectability, awareness, specialized subagents (title / summary / compaction), and plan/build mode as an opinionated pattern hosts may layer.
Index of design notes for the @grida/svg-editor TypeScript SDK — element IR proposal, hit-test architecture, transform pipeline critique, Policy Class glossary.
SVG → Grida IR property mapping and TODO tracker.
Pattern fills for SVG shapes — tiling a subtree as a repeating paint
This document describes the testing methodology and tools used to evaluate SVG rendering accuracy in Grida Canvas.
Status: Active — describes the current import strategy.
Motivation
Motivation
The tool contract. The locked fundamental set, what every tool must self-describe, the result envelope, truncation, and how permissions are evaluated at the tool-call boundary.
Context dump on the transform pipeline in @grida/svg-editor — what's done, what's broken, what's load-bearing for the IR redesign.
A canvas-level organizational primitive for grouping design elements without participating in layout.
Anything that fires a turn besides a human typing in the compositor. Scheduled wakeups, external webhooks (CI / GitHub / generic), programmatic API calls, MCP-pushed events, and agent self-scheduled wakeups. Trigger envelope shape, queue semantics, interactive-vs-hosted execution, agent self-scheduling pattern, lifecycle bounds, and the boundary with background subagents.
A working group draft describing the Unicode Coverage Tracker (UCT) feature for the core engine.
Summary
UX patterns that ride on top of the compositor and push back into the protocol. Queued sends, sidecar chat as ephemeral branch, and memory as a built-on-top layer. The compositor itself, file refs, attachments, mentions, commands, editor context, and the user-view-vs-model-view lowering rules live in compositor.md.
UX Surface documents specify Grida editor's specific practical UX specifications for surface interactions, selection, targeting, and related user interface behaviors.
see PR #408
Why Real WASM Benchmarking Matters
Welcome to the Grida Working Group documentation!