Index
Jay Design Log Index
Written for AI agents. See Log Methodology Note below for details.
Quick reference to find relevant design logs by topic. Design logs capture design decisions as they happen and are not updated after implementation.
Core Concepts & Architecture
| # | Title | Description |
|---|---|---|
| 00 | inspirations | Initial inspirations for the Jay project |
| 01 | what is Jay | Project overview: design-to-code, 3rd party UI inclusions, security |
| 27 | guiding principles of Jay | Core principles guiding the framework |
| 34 | jay stack | Full-stack framework design: rendering phases, component API |
| 68 | jay stack conceptual model | Conceptual model and architecture overview |
| 86 | jay stack full workflow lifecycle | Full lifecycle: setup → agent-kit → dev → render → refresh |
| 87 | jay-stack setup command | Plugin config templating, credential validation, reference generation |
Jay HTML & Templates
| # | Title | Description |
|---|---|---|
| 40 | changing jay-html format | Jay HTML format evolution |
| 44 | css support | CSS styling support in Jay |
| 46 | recursive jay-html | Recursive template support |
| 47 | recursive html context switching | Context switching in recursive templates |
| 57 | style binding support in jay-html | Dynamic style bindings |
| 71 | boolean attribute condition style parsing | Conditional style parsing |
| 75 | slow rendering jay-html to jay-html | Slow phase rendering transformations |
| 78 | unified condition parsing | Unified parsing for code generation and evaluation |
| 163 | built-in bindings and field comparison | jay.params, jay.url.path bindings; field-to-field === comparison; active menu pattern |
| 164 | inline style in body | Body <style> tags crash the template parser; skip, warn, or hoist to head |
| 165 | graceful expression parse errors | Convert expression parse errors to validation messages instead of crashing the page |
Contracts & Type System
| # | Title | Description |
|---|---|---|
| 35 | partial and complementary types | Type composition patterns |
| 38 | Contract File | Jay contract file format (YAML), ViewState and Refs types |
| 45 | View State Types | ViewState type system |
| 50 | rendering phases in contracts | Phase annotations (slow, fast, fast+interactive) for type safety |
| 51 | jay-html with contract references | Contract references in templates |
| 51 | Project Structure Identification | Pages vs Components identification |
| 61 | json-patch typed JSONPointer | Typed JSON operations |
| 79 | linked contracts with mixed phase properties | Linked sub-contracts across rendering phases |
| 95 | jay-action contract references | Reference contract ViewState types from .jay-action output schemas |
| 120 | record type in jay-action | record(T) type notation for typed Record maps in action schemas |
| 122 | enum name collision across linked contracts | Fix import shadowing and duplication when linked contracts share enum names |
| 152 | phase-aware contract props | Optional phase on props so the framework can validate binding availability |
Full-Stack Components & Rendering
| # | Title | Description |
|---|---|---|
| 36 | Partial Rendering | Partial/incremental rendering |
| 37 | Composite Component | Composite component patterns |
| 49 | full stack component rendering manifest | Manifest for full-stack rendering |
| 52 | jay-stack client-server code splitting | Client/server code splitting |
| 54 | render result monads | Result type patterns for rendering |
| 55 | full stack component parameter flow refinement | Props and parameter flow |
| 56 | deep merge view states with track-by | Array merging with track-by keys |
| 58 | jay-stack headless component resolution | Headless component resolution |
| 62 | relocate deep merge for stack-client-runtime | Client runtime deep merge |
| 72 | skip client script for non-interactive components | Optimization for static components |
| 84 | headless component props and repeater support | Props, multiple instances, forEach, jay: prefix |
| 85 | rendering phases and agent kit for agentic generation | Phases + contract/action discovery; agent-kit folder, markdown content → jay-html |
| 90 | headless instances in interactive forEach | Allow fast/interactive-only headless components inside forEach (no slow phase) |
| 111 | nested headfull full-stack components | Headfull components with own jay-html + SSR via headless pipeline template injection |
| 123 | deeply nested headfull and headless components | Gap analysis: headfull+keyed headless, headfull-in-headfull, headless-in-headfull |
| 141 | fast phase request context | Cookie access + response headers (Cache-Control) in fast phase for wix-members |
Server Actions & Client-Server Communication
| # | Title | Description |
|---|---|---|
| 63 | jay-stack server actions | RPC-style server actions: makeJayAction, makeJayQuery, action registry |
| 82 | automatic server-side action service injection | Auto-inject services when actions called from server code |
| 129 | streaming actions | makeJayStream with AsyncGenerator handlers, SSE transport |
| 131 | multipart file upload in actions | withFiles() opt-in for binary uploads via FormData, JayFile temp paths |
Plugin System
| # | Title | Description |
|---|---|---|
| 39 | Plugin package | Plugin package requirements and structure |
| 43 | Jay Package | Jay package format |
| 60 | plugin system refinement and dynamic contracts | Plugin.yaml, contract resolution, dynamic contract generation |
| 66 | transitive plugin dependency resolution | Plugin dependency resolution |
| 80 | exposing dynamic contracts for agentic generation | CLI and dev server contract generation for AI agents |
| 87 | jay-stack setup command | Plugin config templating, credential validation, references |
| 88 | PR 158 review guide | Review guide for export_import branch (Figma vendor + plugin resolution) |
| 89 | PR 158 merge concerns | Merge conflicts, duplicate work, and decisions for PR #158 into main |
| 130 | plugin routes and templates | Plugins provide pages (jay-html + page.ts) as routes; project overrides |
| 142 | plugin CLI commands | jay-stack run <plugin>/<command> for admin/batch operations |
| 145 | pluggable jay-html validation | Plugin-provided validation rules for jay-html with agent-friendly feedback |
| 147 | jay-html validation rules catalog | Complete catalog of all validation rules across wix-media, SEO, and a11y |
| 151 | design system validator plugin | Static CSS analysis against DESIGN.md tokens; replaces Happy DOM approach |
| 154 | plugin package shipping validation | Validate agent-kit directory is listed in package.json files |
| 155 | markdown plugin | Markdown rendering: directory-to-pages, inline content, code + mermaid |
| 156 | keyed headless component props | YAML body props for keyed headless components; consolidation with jay-params |
| 157 | interactive plugin setup | Interactive prompts in plugin setup handlers; move Wix logic out of create-jay |
| 159 | setup pipeline re-initialization | Re-init services after each plugin setup; suppress init noise; cascade deps |
| 160 | deprecate editor packages | Move editor-client/protocol/server to _deprecated; remove from stack-cli |
| 161 | markdown image url resolution | Rewrite relative image URLs in markdown; copy media to public; CDN mapping |
| 162 | structural headfull components | Allow headfull components without .ts code file; passthrough from contract |
| 166 | a11y form and label validation rules | Extend a11y-validator: checkbox/radio, ARIA name integrity, duplicate ids, label hygiene |
| 167 | a11y nested interactive elements | a11y rule: focusable elements nested inside links/buttons (WCAG 4.1.2) |
| 168 | font fallback metrics | Metric-matched fallback @font-face to prevent CLS on font load; validation + CLI tool |
| 169 | data files plugin | CSV/YAML/JSON/JSONL data source plugin: list view, item view, per-item pages, cross-references |
| 170 | seo validator false positives | Fix false positives: component vs page detection, html-string awareness, fetchpriority |
| 171 | dev-only plugin routes | devOnly flag on plugin routes — dev-server tooling metadata on RouteInfo |
| 172 | plugin-framework-version-compatibility | Registry-based plugin↔framework compat; plugins compat, install preflight, doctor |
| 173 | aiditor-settings-plugin-contributions | Project settings tabs: template path, materialization, walk-up resolver, devOnly |
Services & Initialization
| # | Title | Description |
|---|---|---|
| 64 | client context initialization and plugin init | Client context and plugin initialization |
| 65 | makeJayInit builder pattern | Server initialization builder API |
| 67 | registerReactiveGlobalContext | Global reactive context registration |
Routing & Navigation
| # | Title | Description |
|---|---|---|
| 53 | jay-stack environment query parameter handling | Query parameter handling |
| 69 | route priority ordering for static vs dynamic routes | Route matching priority |
| 70 | static route param inference | Static route parameter inference (superseded by #113) |
| 113 | explicit route params for static overrides | Replace auto-inference with <script type="application/jay-params"> |
| 117 | fast phase query parameters | Type-safe query string access in fast phase only (props.query) |
| 163 | built-in bindings and field comparison | jay.params, jay.url.path bindings in page templates |
Compiler & Build System
| # | Title | Description |
|---|---|---|
| 04 | compiler | Initial compiler design |
| 20 | component compiler | Component compilation |
| 25 | building the compiler | Compiler architecture, code splitting |
| 28 | runtime compiler | Runtime compilation |
| 29 | algorithm to split safe code | Safe code splitting algorithm |
| 73 | jay-stack validate command | Plugin validation command |
| 74 | watch linked style files in dev server | Dev server file watching |
| 118 | jay-html-compiler refactor | Extract shared algorithms + split by compilation target |
| 134 | production build | Two-server production architecture: main server + slow render server |
| 134a | build pipeline | Per-instance compilation, shared chunks, Vite build strategy |
| 134b | main server | Production request handling: fast phase + SSR with pre-built artifacts |
| 134c | slow render server | Webhook invalidation, per-instance rebuild, versioned bucket building |
| 134d | server build | Compiling page.ts, actions, services, init.ts to production JS |
| 136 | loadParams route context | Passing inferred/route params to loadParams for multi-prefix filtering |
| 139 | wix deployment separation | Split build into frontend (CDN) + backend (container); Cloudflare-compatible fetch handler |
| 140 | production smoke test | Dedicated example project validating dev, production self-hosted, and production CDN modes |
| 143 | artifact store abstraction for BaaS | ArtifactStore interface, serve-only export, pre-imported modules for cloud deployment |
| 144 | per-route server elements | One server-element.js per route instead of per instance; render from ViewState, not literals |
| 145 | pluggable jay-html validation | Plugin-provided validation rules for jay-html files with agent-friendly feedback |
| 146 | css performance fixes | CSS minification in production build, preload hints for route CSS |
| 150 | build content hash | SHA-256 content hash of build output for deployment client/server sync |
| 153 | npm create jay | Interactive project scaffolding: name, plugin selection, agent-kit, setup banner |
| 158 | staged npm publish | Two-phase publish: stage all packages without OTP, then bulk-approve with single OTP |
| 147 | jay-html validation rules catalog | Complete catalog of all validation rules across wix-media, SEO, and a11y |
| 165 | graceful expression parse errors | Convert expression parse errors to validation messages instead of crashing the page |
| 166 | a11y form and label validation rules | Extend a11y-validator: checkbox/radio, ARIA name integrity, duplicate ids, label hygiene |
| 174 | undefined css variable validation | Validate that CSS var(--name) references have corresponding :root definitions |
| 175 | sitemap generation and robots validation | jay-stack sitemap command + robots.txt existence validation |
| 176 | validation warning suppression audit | Every warning must be suppressible; jay-validations script; promote some to errors |
| 177 | tree-shake unused plugin client bundles | Only preload shared chunks each page actually imports; per-route sharedDeps |
| 178 | compiler-free production runtime | Eliminate compiler deps from serve + rebuild; use page-parts.json for rebuild |
Runtime & State Management
| # | Title | Description |
|---|---|---|
| 03 | runtime | Runtime architecture |
| 06 | state management | State management patterns |
| 08 | Jay Component | Component lifecycle and API |
| 22 | serialized mutable | Serialized mutable state |
| 30 | Jay Context API | Context API design |
| 31 | rename createState to createSignal | Signal-based reactivity |
| 32 | Reactive Pairing fixes | Reactive pairing fixes |
| 133 | html entities in text nodes | HTML entities decoded by SSR but not by client-side createTextNode/textContent |
Events & Interactivity
| # | Title | Description |
|---|---|---|
| 05 | events | Event handling |
| 09 | Safe events | Safe event handling |
| 13 | Redo Events | Event system redesign |
| 14 | References API | Element references API |
| 18 | update on conditional | Conditional updates |
| 24 | refactor refs | Reference system refactoring |
Security & Sandboxing
| # | Title | Description |
|---|---|---|
| 001 | 3rd party code problem | Third-party code security issues |
| 02 | Jay Element vs Component | Secure model comparison |
| 07 | nested components | Nested component security |
| 10 | building components - a challenge | Component building challenges |
| 12 | Secure Architecture | Security architecture |
| 15 | main to worker communication protocol | Worker communication |
| 16 | context api | Context API security |
| 17 | main and sandbox secure contexts | Secure context separation |
| 21 | alternative to context API | Context API alternatives |
Server-Side Rendering (SSR) & Hydration
| # | Title | Description |
|---|---|---|
| 11 | server side rendering | SSR design |
| 23 | JSON compare and patch | JSON diffing for SSR hydration |
| 48 | Jay Stack Services | Service injection for SSR |
| 50 | jay stack - headless configuration | Headless SSR configuration |
| 93 | client hydration | Hydrate server-rendered DOM: skip static HTML, adopt dynamic nodes |
| 94 | SSR streaming renderer | Compile jay-html to streaming server render, no DOM APIs |
| 98 | route-based server-element output | Server-element files follow route structure (consistent with DL96) |
| 99 | hydration coordinate alignment bugs | Fix forEach prefix, conditional+ref counter, containerCoordinate |
| 100 | hydrate conditional creation fallback | Level 3 hydration: create elements for false-at-SSR conditionals |
| 102 | headless instance SSR and hydration compilation | Server-element and hydrate targets for <jay:xxx> headless instances |
| 103 | coordinate pre-processing for SSR hydration consistency | Pre-assign jay-coordinate-base to all nodes; server and hydrate read it |
| 104 | hydration test plan | Test plan: static, conditionals, forEach, slowForEach, headless (a–d) |
| 106 | hydrate dynamic elements with Kindergarten | One Kindergarten per parent with mixed children; STATIC sentinel; _setGroup pattern |
| 107 | dev server consistency and phase optionality | Slow cache on/off parity, optional phases, SSR disable, build cleanup, loadParams cache |
| 108 | no-contract phase defaults for jay-stack | Without contract: all data is fast+interactive, no slow phase, remove noMainContract |
| 109 | unified dev server phase pipeline | Fix instance fast render gate for fast-only pages, hydration initial update |
| 110 | filesystem-based slow render cache | Cache loadParams per route, embed cache metadata in pre-rendered jay-html |
| 112 | hydration view state consistency | Hydrate with SSR ViewState (matches DOM), then update with client ViewState |
| 115 | slowForEachItem adopt element wrapping | Wrap slowForEachItem callback in adoptElement for multi-child nested slow forEach |
| 116 | client import rewriting in library builds | Fix bare @jay-framework/* imports not rewritten to /client in vite build output |
| 119 | async data SSR and hydration | Fix async data (Promise types) through SSR swap scripts, hydrate compiler, and ViewState serialization |
| 126 | coordinate assignment rules | Complete rules for coordinate assignment across forEach, slowForEach, headless, headfull nesting |
| 127 | SEO head injection | Render SEO data (title, meta, OG tags) from ViewState into <head> during SSR |
| 148 | head tag bindings | {binding} support in jay-html <title>, <meta>, <link> — resolved against ViewState at SSR time |
| 149 | script tags in jay-html | Reject inline scripts (use page.ts), allow external 3rd-party scripts in <head> |
| 135 | display contents for wrapper elements | Add display:contents to compiler-generated wrappers so they don't break sticky/flex/grid |
| 137 | production build self-containment | Strip headfull tags, source CSS refs, embed contracts, relative manifest paths — no src/ at runtime |
| 138 | safe refs stubs for unused contract refs | No-op proxy for contract-declared refs absent from template; prevents crashes in shared plugin code |
Developer Experience & Tooling
| # | Title | Description |
|---|---|---|
| 26 | jay start - compiling sandbox application |
Dev server startup |
| 33 | Jay 4 React | React integration |
| 41 | package naming migration to @jay-framework | Package naming convention |
| 42 | editor integration | Editor/IDE integration |
| 76 | AI Agent Integration | AI agent automation API |
| 77 | automation dev server integration | Automation API for dev tools |
| 80 | materializing dynamic contracts for agentic generation | CLI and dev server contract materialization for AI agents |
| 81 | dev server test mode | Health/shutdown endpoints and timeout for smoke testing |
| 83 | dev server logging and timing | Clean output, verbose mode, timing for render phases |
| 85 | rendering phases and agent kit for agentic generation | Agent-kit folder: instructions, contracts, markdown content with headless annotations |
| 91 | WebMCP plugin for jay-stack | Generic WebMCP support: automation→tools/resources/prompts, plugin packaging |
| 114 | documentation gaps and updates | Audit of docs vs design logs; gap list and update plan |
| 124 | contract props and params consistency | Ensure contracts declare props/params; agent-kit authoring docs + validate checks |
| 125 | plugin agent-kit | agent-kit --mode plugin for AI agents creating plugins (contracts, components, actions) |
| 128 | unfolded variant view | Page freeze: capture ViewState, render static SSR snapshots for side-by-side comparison |
| 92 | Gemini agent plugin for jay-stack | Embedded AI agent: Gemini API, .jay-action metadata, chat contract, page automation |
| 97 | Contract-based tool descriptions for gemini agent | Semantic tool descriptions from .jay-contract via server action, not embedded in HTML |
| 132 | ui-kit headless primitives | Popover menu, scroll carousel, tab switcher, clipboard copy — thin JS over HTML/CSS |
| 142 | ui-kit Add Menu contribution | M19.3 add-menu yaml; U1–U3 done; ships with aiditor smoke |
Quick Lookup by Task
"I need to understand the rendering pipeline"
→ See #34 (jay stack), #50 (rendering phases), #52 (code splitting), #75 (slow rendering), #94 (SSR streaming)
"I'm working on contracts and types"
→ See #38 (Contract File), #45 (View State Types), #50 (phases in contracts), #79 (linked contracts)
"I'm adding server-side functionality"
→ See #63 (server actions), #48 (services), #65 (makeJayInit)
"I'm building or modifying a plugin"
→ See #39 (Plugin package), #60 (plugin system refinement), #66 (plugin dependencies), #84 (headless component props)
"I'm working with headless components"
→ See #50 (headless configuration), #58 (headless resolution), #84 (props, multiple instances, jay: prefix), #90 (forEach instances without slow phase)
"I'm working on the compiler"
→ See #25 (building the compiler), #28 (runtime compiler), #29 (code splitting), #78 (condition parsing)
"I'm adding client-side interactivity"
→ See #06 (state management), #31 (createSignal), #30 (Context API), #09 (safe events), #93 (client hydration)
"I'm working on SSR or hydration"
→ See #11 (SSR concept), #93 (client hydration), #94 (SSR streaming renderer), #75 (slow rendering), #72 (skip client script), #106 (Kindergarten for mixed children)
"I'm working on the dev server"
→ See #26 (jay start), #74 (file watching), #77 (automation integration), #81 (test mode), #107 (consistency and phase optionality)
"I need to understand security model"
→ See #001 (3rd party problem), #12 (Secure Architecture), #17 (secure contexts)
"I'm working on AI agent integration"
→ See #76 (AI Agent Integration), #77 (automation dev server), #80 (contract materialization for agents), #85 (agent kit and rendering phases), #91 (WebMCP plugin), #92 (Gemini agent plugin)
→ Agent kit skills: .cursor/skills/jay-agent-kit/ (main), jay-html-authoring/, jay-cli-commands/, jay-contracts-and-plugins/, jay-dev-server-test/
"I need to understand the full workflow lifecycle"
→ See #86 (full workflow lifecycle: setup → agent-kit → coding → slow → fast → interactive → refresh)
"I'm working on the production build"
→ See #134 (production build: two-server architecture, build pipeline, artifact layout)
Notes
- Design logs are not updated after initial writing - they capture decisions at a point in time
- Implementation may deviate from original design - check "Implementation Results" sections
- Some logs have multiple files with the same number (e.g., 50, 51) - these are related but separate topics
- Diagram files (.mmd, .svg, .png) accompany some design logs for visual reference
Log Methodology Note
Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.