Skip to content

feat(appkit): add dev-only design pages plugin and ui-only template - #680

Draft
MarioCadenas wants to merge 32 commits into
work/2-appkit-plugin-add-with-auth-mofrom
work/1-design-plugin-dev-only-design-
Draft

MarioCadenas wants to merge 32 commits into
work/2-appkit-plugin-add-with-auth-mofrom
work/1-design-plugin-dev-only-design-

Conversation

@MarioCadenas

@MarioCadenas MarioCadenas commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #679 (KIT-2). Merge #679 first; this PR's base will then move to main.

Adds a dev-only design() plugin (beta) that serves design pages at full size, and an empty ui-only app template (server + design) for quick PoCs.

What it does

  • /design renders the default export of client/src/design/index.tsx. /design/<name> renders client/src/design/pages/<name>.tsx. Each page renders on its own at full size with the app's styles (client/src/index.css) and hot reload. Anything else under /design returns 404.
  • Multiple pages. With react-router (the template ships it), design pages share a router whose basename is /design, so <Link to="/orders"> stays at /design/orders. The requested page is imported directly and other pages load only when navigated to, so an unfinished draft breaks only its own URL.
  • Readiness. GET /design/__status returns { ready, pages }. ready means client/src/design/index.tsx exists, isn't the template placeholder (export const designPlaceholder = true), and has painted since it last changed. After first paint (and after each hot update), the page posts { type: "appkit:design-ready", version: 1, page, pages } to window.parent (else window.opener), only to the configured builderOrigin (bare origins only; "*" is rejected).
  • Theme. The template's index.html and the /design page declare color-scheme: light dark; the theme already follows prefers-color-scheme.
  • Source mapping. Elements carry the dev server's existing data-source="file:line:col" attributes, so the app builder's own element inspector can map a click back to source. The plugin has no picker or selection store of its own.
  • Production: nothing is mounted and /design returns 404. The manifest is deliberately not devOnly: a dropped plugin couldn't claim /design, and the SPA fallback would serve the app's index.html for it with a 200.
  • Plugin hook: plugins can add Vite plugins to the dev server through an optional vitePlugins() method. That's how the design plugin serves its pages.
  • Template: the ui-only entry in tools/generate-app-templates.ts (features: design), a gated client/src/design/index.tsx sample page, and a README line.

How I checked it

  • Live in Chromium.
    • /design and /design/orders rendered their pages full size with data-source attributes, and no page errors.
    • /design/missing, /design/a/b and /design/orders.tsx returned 404, and /api/design/selection returned 404 (no API).
    • App pages are untouched.
  • Tests. Unit tests cover page resolution (index, named pages, .jsx, missing pages, paths outside /design) and the production 404.
  • Commands. pnpm build, pnpm docs:build, pnpm -r typecheck, pnpm check, knip and pnpm test (312 files) all pass. The bundle baseline is refreshed.

Not done

  • ui-only wasn't generated with databricks apps init (needs the CLI and network); only the template files changed.

Task: KIT-1 (app-kit/1)

This pull request and its description were written by Isaac.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 1.3 MB (+38 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 1.3 MB (+43 KB) 477 KB (+15 KB)
Type declarations 466 KB (+907 B) 169 KB (+427 B)
Source maps 2.6 MB (+73 KB) 885 KB (+23 KB)
Other 11 KB 3.7 KB
Total 4.4 MB (+117 KB) 1.5 MB (+39 KB)
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 106 KB (+27 B) 2.5 KB (-1 B) 109 KB (+26 B) external 344 KB (-56 B)
./beta 114 KB (+10 KB) 485 B 114 KB (+10 KB) external 339 KB (+28 KB)
./testing 45 KB (+1 B) 32 KB (+28 B) 77 KB (+29 B) external 224 KB (+42 B)
./tsdown 520 B 0 B 520 B external 813 B
./type-generator 26 KB (+31 B) 0 B 26 KB (+31 B) external 74 KB (+42 B)

Chunks:

Entry Chunk Load Size (gz)
. index.js initial 101 KB
. utils.js initial 4.6 KB
. remote-tunnel-manager.js lazy 2.5 KB
./beta beta.js initial 94 KB
./beta modular.js initial 6.0 KB
./beta stream-manager.js initial 5.9 KB
./beta service-context.js initial 4.2 KB
./beta databricks.js initial 3.3 KB
./beta client.js initial 647 B
./beta index.js initial 20 B
./beta supervisor-api.js lazy 192 B
./beta databricks.js lazy 178 B
./beta index.js lazy 115 B
./testing manifest.js initial 32 KB
./testing index.js initial 10 KB
./testing wide-event-emitter.js initial 2.9 KB
./testing index.js lazy 28 KB
./testing remote-tunnel-manager.js lazy 2.5 KB
./testing utils.js lazy 1.8 KB
./tsdown index.js initial 520 B
./type-generator index.js initial 26 KB

@databricks/appkit-ui

npm tarball (packed): 402 KB (+4.8 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 431 KB (+2.0 KB) 148 KB (+1003 B)
Type declarations 269 KB (+1.8 KB) 99 KB (+934 B)
Source maps 857 KB (+4.1 KB) 288 KB (+2.0 KB)
CSS 16 KB 3.2 KB
Other 19 KB (+19 KB) 1.8 KB (+1.8 KB)
Total 1.6 MB (+27 KB) 539 KB (+5.6 KB)
Per-entry composition (consumer bundle — deps bundled, peerDeps external)
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
./js 5.3 KB 49 KB 55 KB 208 KB 14 KB
./js/beta 2.1 KB 0 B 2.1 KB 0 B 5.0 KB
./react 433 KB (+68 B) 49 KB 481 KB (+68 B) 1.3 MB (+3 B) 178 KB (+126 B)
./react/beta 4.9 KB (+73 B) 0 B 4.9 KB (+73 B) 0 B 13 KB (+171 B)

Chunks:

Entry Chunk Load Size (gz)
./js index.js initial 5.2 KB
./js chunk initial 120 B
./js apache-arrow lazy 49 KB
./js/beta beta.js initial 2.1 KB
./react index.js initial 431 KB
./react tslib initial 2.1 KB
./react apache-arrow lazy 49 KB
./react/beta beta.js initial 4.9 KB

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 1 · Fail · 3 critical, 2 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The canvas, multi-selection, notes, persistence across a real restart, and production 404 work, and the automated suite passes. The handoff is not reliable: normal selections can lack source locations, contain stale props, and include screenshots missing visible content. Valid wrapped components are also omitted, and concurrent reads can falsely report no pending selections.

Required

  • critical: Selecting AppKit UI components can omit the required source location or report an unrelated ancestor. (packages/appkit-ui/src/react/design/inspect.ts:86–87)
    Proof: Ran the design plugin in Chrome using the branch build and appkit-ui with published-package exports. Selected Primary action in the supplied ExampleCard template: the picker displayed no source location, and both GET /api/design/selection and .appkit/design-selection.json omitted source for Button. Selecting Library button on the running app instead saved the enclosing main element location. The picker only reads the closest native data-source attribute; dependency components are excluded from the existing JSX transform. See canvas-selection.png and checks.txt.
  • critical: The picker persists stale component props after ordinary React updates. (packages/appkit-ui/src/react/design/inspect.ts:69–80)
    Proof: In Chrome, incremented a parent useState counter three times, then selected the child LiveCard button and sent it. The visible text and persisted text were Count: 3, but persisted props.count was 2. A separate sequence reproduced rendered/saved pairs 0/0, 1/0, 2/2, 3/2, 4/4. Walking the DOM-attached fiber without resolving its current alternate reads the previous props on alternating updates. See app-selection.png and the saved endpoint output in checks.txt.
  • critical: Saved screenshots omit visible images and canvas content. (packages/appkit-ui/src/react/design/inspect.ts:119–125)
    Proof: Selected and sent a real component preview containing a same-origin image and an HTML canvas chart. Chrome displayed both, as shown in canvas-selection.png. Opened the actual JPEG referenced by the saved selection: the image became a broken-image icon and the chart disappeared. agent-screenshot.jpeg is that unedited file. Cloning and serializing the DOM does not preserve canvas pixels or embed image resources.
  • major: The canvas silently omits PascalCase memo and forwardRef component exports. (packages/appkit-ui/src/react/design/design-canvas.tsx:38–40)
    Proof: Added MemoDraft = memo(...) and RefDraft = forwardRef(...) alongside ordinary function previews in the isolated test app. Browser inspection found only BrokenDraft, RealPreview, and ExampleCard frames; MemoDraft and RefDraft were absent. An independent server-rendering probe likewise rendered only the ordinary function. Both wrappers are valid React component types but typeof returns object, which the filter rejects. checks.txt includes the actual fixture exports and browser frame list.
  • major: Reading selections during a write can falsely return an empty pending list. (packages/appkit/src/plugins/design/store.ts:63–67,107–109)
    Proof: Seeded one selection, appended 100 small selections, and concurrently polled read() from four readers without clearing. Of 1,019 reads, 104 returned an empty selections array; a new store after completion read all 101 entries. writeFile truncates the live file, reads bypass the write queue, and parse failures are converted to an empty list. This proves transient incorrect reads, not durable loss after completed writes. Runnable reproduction and output are included in checks.txt.

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 2 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

The five earlier findings are fixed, and I found no regressions from those fixes. Browser checks against the built UI package, the full test suite, typechecking, and read-only lint/format checks passed. There are no remaining findings in this round.

No findings.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from af1f4a2 to aa65b0d Compare October 20, 2026 13:01
@MarioCadenas
MarioCadenas changed the base branch from main to work/2-appkit-plugin-add-with-auth-mo October 20, 2026 13:01
@MarioCadenas MarioCadenas changed the title Design plugin (dev-only /design) and ui-only template feat(appkit): add dev-only design plugin and ui-only template Oct 20, 2026
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 5 · Fail · 1 critical, 1 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The design canvas, selection handoff, persistence and production 404 behavior work in the exercised cases, and all 50 targeted tests pass. The screenshot requirement is incomplete: selecting an absolutely positioned element can silently save an entirely blank image. The added CLI also omits declared resource defaults from deployment variables in an unusual supported case.

Required

  • critical: Selecting an absolutely positioned element can silently send a blank screenshot to the agent. (packages/appkit-ui/src/react/design/inspect.ts:145-151 and 201-211)
    Proof: In Chrome at /design, selected a visible red button with position:absolute, left:180px, top:70px, width:220px and height:60px, then sent it through the actual picker. The UI reported success and persisted a JPEG, but that 220x60 image contained zero nonwhite pixels. The original button and saved image are compared in screenshot-failure.png. prepareClone retains the root positioning offsets inside a crop sized only to the element dimensions, placing the button outside its screenshot.
  • major: The new plugin add command omits manifest resource defaults from generated deployment variables. (packages/shared/src/cli/commands/plugin/add/plan.ts:396)
    Proof: Ran the source CLI plugin add analytics --yes against a temporary app whose analytics manifest declared fields.id.value="warehouse-default". The command wrote DATABRICKS_WAREHOUSE_ID=warehouse-default to .env, but databricks.yml referenced ${var.sql_warehouse_id} with neither a default nor target assignment. A direct planning probe also reported no missing values. checks-r5.txt includes the command output and generated configuration; no deployment was attempted.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 41050726525 -R databricks/appkit -n appkit-template-0.89.0-pr.31ef605-work-1-design-plugin-dev-only-design-680 -D appkit-pr-680 \
  && unzip -o "appkit-pr-680/appkit-template-0.89.0-pr.31ef605-work-1-design-plugin-dev-only-design-680.zip" -d "appkit-pr-680" \
  && databricks apps init --template "appkit-pr-680"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from aa65b0d to 4d00fbf Compare October 20, 2026 14:22
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 6 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

Both previous findings are fixed at the reviewed commit. Chrome reproduced the blank screenshot with the previous code and verified the saved JPEG with the fix; actual plugin-add runs preserved manifest defaults in deployment YAML. The focused regression checks passed, with no remaining findings in this round.

No findings.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from 4d00fbf to acf5c0f Compare October 20, 2026 15:37
@MarioCadenas
MarioCadenas added this pull request to stack #681 October 20, 2026 16:09
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 7 · Fail · 3 critical

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The main canvas, source tracing, persisted handoff, production 404 behavior, and ui-only template work in the exercised paths. Three browser-proven faults remain: open dialogs disable the picker, completing a send discards selections added during that send, and screenshots omit typed values in uncontrolled inputs. The repository was left unchanged.

Required

  • critical: Opening an AppKit dialog makes the design picker unclickable, preventing selection of modal content. (packages/appkit-ui/src/react/design/design-picker.tsx:237)
    Proof: Ran node /tmp/appkit-design-round7/browser.mjs in Chromium against the current source. Opened the actual AppKit Dialog using its trigger, then attempted to click Select; Playwright timed out. Computed pointer-events was none on both body and the picker button, versus auto on dialog content. The picker host only sets position/z-index and inherits the disabled pointer events. See round7-dialog-blocked.png, round7-interactions.webm, and round7-checks.txt. Reproduce at http://127.0.0.1:5197/ by clicking Open sample dialog, then Select.
  • critical: A completed send silently discards selections added while that request was pending. (packages/appkit-ui/src/react/design/design-picker.tsx:143 (selection changes remain enabled at line 105))
    Proof: In the Chromium run, held the POST response using Playwright routing, selected Absolutely positioned action, and clicked Send 1 to agent. While the request was pending, selected Translated action; the UI offered an enabled Send 2 to agent button. Released the original request: both selections disappeared and the UI reported Sent, but the request and persisted endpoint contained only Absolutely positioned action. The successful send clears all current picks, including the unsent addition. See round7-interactions.webm and round7-checks.txt.
  • critical: Screenshots sent to the agent omit the current typed value of an uncontrolled text input. (packages/appkit-ui/src/react/design/inspect.ts:228 (prepareClone does not preserve live input state))
    Proof: Ran node /tmp/appkit-design-round7/form-check.mjs in Chromium. Filled a normal input with REVIEW TITLE, selected it, and sent it through the picker. The saved JPEG showed the Enter title placeholder instead of the visible text; it was byte-identical to a capture taken after clearing the input. The live value exists as a DOM property, but XML serialization retains the empty value attribute. round7-form-screenshot.png compares the visible control with the actual persisted screenshot; round7-checks.txt records the assertion.

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 8 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

F8, F9 and F10 are fixed: browser checks confirmed modal selection, preservation of later picks and edited notes during a pending send, and screenshots containing current form values. Focused tests and nearby runtime checks passed, with no remaining findings in this review round. The repository was left unchanged.

No findings.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from 9bdf7b9 to ad6dc6e Compare October 26, 2026 14:19
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 10 · Fail · 3 critical

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The change does not meet the full task: the running app has no selection interface, open dialogs block selection, and clicking an SVG path saves a blank screenshot. The normal canvas handoff, source metadata, persistence across a server restart, and production 404 behavior worked locally. All 71 tests exercised passed, including the previously failing React type test.

Required

  • critical: The design plugin does not provide element selection in the running app. (packages/appkit/src/plugins/design/vite-plugin.ts:62; packages/appkit-ui/src/react/design/design-canvas.tsx:194)
    Proof: Ran a local app with server() and design(), successfully selected and sent two elements from /design, then navigated to /. The real app component rendered, but Playwright found zero #appkit-design-picker roots and zero Select buttons. Source inspection confirms the picker is mounted only by DesignCanvas, whose entry is served only for /design and /design/. See running-app-without-picker.png and review-checks.txt. This omits the explicit requirement to select elements in the running app.
  • critical: Opening a normal AppKit dialog prevents users from enabling selection for its contents. (packages/appkit-ui/src/react/design/design-canvas.tsx:100; packages/appkit-ui/src/react/design/design-picker.tsx:166)
    Proof: Rendered an AppKit Dialog in a design preview and opened it through DialogTrigger. Clicking header button[aria-pressed] timed out because the z-50 dialog overlay intercepted pointer events; the dialog remained open and aria-pressed stayed false. The Select control sits in the z-10 header outside the dialog, and there is no activation keyboard shortcut. Enabling selection first consumes the dialog trigger click through the picker listeners. See modal-picker-blocked.png and the browser trace in review-checks.txt; the live fixture includes Open preview dialog.
  • critical: Clicking an SVG icon path sends a blank screenshot to the agent. (packages/appkit-ui/src/react/design/inspect.ts:228)
    Proof: In Chrome, enabled Select, clicked a visible red SVG path inside an icon button, and sent the selection. The persisted element correctly had tag path and a screenshot filename, but fetching and decoding that JPEG produced a 32 by 32 image with zero non-white pixels. The capture clones the path into an HTML div without its owning SVG, so the stored screenshot loses the selected visual. The exact fixture, saved metadata, and pixel analysis are in review-checks.txt; IconPreview in the live canvas reproduces it.

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 11 · Fail · 2 critical

Does the change do what the task asked? No. Gate: major and worse must be fixed.

F12 and F13 are fixed and worked in Chromium, but the change does not yet meet the supplied task. F11 remains against the original running-app selection requirement; the claimed later scope change was not confirmed. Pressing the advertised Escape shortcut after selecting dialog content also closes the dialog and silently loses its screenshot when sent.

Required

  • critical: The design plugin still does not provide element selection in the running app. (packages/appkit/src/plugins/design/vite-plugin.ts:62; packages/appkit-ui/src/react/design/design-canvas.tsx:216)
    Proof: Opened the same temporary AppKit application at /design and / in Chromium. Selection works at /design; the running app has zero #appkit-design-picker roots and zero Select buttons. Executing the Vite plugin hooks also showed / and /orders passing through unchanged, with no app-page picker injection. Git history corroborates intentional removal, but does not independently establish the cited human scope change.
  • critical: Pressing Escape to stop selecting dialog content closes the dialog and silently saves the selection without its screenshot. (packages/appkit-ui/src/react/design/design-picker.tsx:184; packages/appkit-ui/src/react/design/design-picker.tsx:218; packages/appkit-ui/src/react/design/inspect.ts:232)
    Proof: Reproduced twice in Chromium: open a normal AppKit Dialog, enable Select, pick its title, press the advertised Esc-to-stop shortcut, then Send 1 to agent. Escape closes the dialog while the picker retains one selection; sending reports success. GET /api/design/selection and the on-disk .appkit/design-selection.json both contain selection 48e4923a-0cba-4eb9-8cd3-2f4daed9766a without a screenshot field. A control stopping selection with the header button keeps the dialog open and saves its screenshot. Escape is allowed to reach the dialog, and the later capture skips the now-detached element bec

@MarioCadenas MarioCadenas changed the title feat(appkit): add dev-only design plugin and ui-only template feat(appkit): add dev-only design pages plugin and ui-only template Oct 27, 2026
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 12 · Fail · 2 critical, 1 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The design pages and ui-only starter work, including hot reload and production 404s. The change does not meet the supplied task because element selection and persistent agent handoff are absent. An unrelated unfinished draft can also break an otherwise valid design page.

Required

  • critical: Users cannot select multiple elements or attach a note in either the design canvas or the running app. (packages/appkit/src/plugins/design/vite-plugin.ts:39; packages/appkit/src/plugins/server/vite-dev-server.ts:89)
    Proof: In Chromium, /design rendered the template sample with only its Primary action button. Clicking the heading and button produced no selection interface, note field or send control; the running app likewise had no picker and its button performed its ordinary action. Native elements carried data-source attributes, but source inspection confirms the entry module only renders the page and installs no selection/inspector UI. See validation.txt and design-review.webm.
  • critical: The required persisted selection record and builder-agent pull interface are not implemented. (packages/appkit/src/plugins/design/index.ts:28; packages/appkit/src/plugins/design/)
    Proof: GET and POST /api/design/selection both returned 404 from the running development app, and .appkit/design-selection.json did not exist after the browser interaction. The complete plugin contains only page resolution/rendering and the production 404; searching packages and template found no selection store, screenshot capture, selection endpoint or design MCP implementation. Consequently no record containing component, source location, props, screenshot and note can be saved or retrieved. See validation.txt.
  • major: Eagerly importing every design page lets an unrelated unfinished draft break a valid route. (packages/appkit/src/plugins/design/vite-plugin.ts:45)
    Proof: After /design rendered successfully, I added client/src/design/pages/unfinished.tsx importing a component that did not exist yet, without changing the index or visiting /design/unfinished. Reloading /design displayed a Vite unresolved-import overlay for unfinished.tsx and the valid index heading disappeared. Removing only the unfinished page restored /design. The entry module imports all matching pages with eager:true before choosing the requested one. See broken-draft.png, design-review.webm and validation.txt.

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 13 · Fail · 2 critical

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The broken-draft loading bug is fixed, including live browser rendering and hot reload beside an unfinished page. The current task still explicitly requires multi-selection with notes and a persisted agent handoff; both remain absent despite their intentional removal, so the change does not meet all stated requirements.

Required

  • critical: Users still cannot select multiple elements or attach a note in either the design canvas or the running app. (packages/appkit/src/plugins/design/vite-plugin.ts:40; packages/appkit/src/plugins/server/vite-dev-server.ts:87)
    Proof: Ran the actual source AppKit server with server() and design() in an isolated local fixture. In Chrome at /design and /, clicked one shared component and Shift-clicked another, then tried Cmd+K: only native text highlighting appeared, with zero textboxes, dialogs or toolbars and only the original application buttons. Clicking a button invoked its original handler. Source inspection confirms the generated entry only mounts Page and the server adds data-source metadata without a picker, note field or send handler. See design-selection.png, app-selection.png, browser-checks.webm and checks.txt.
  • critical: The required persisted selection record and builder-agent pull interface are still not implemented. (packages/appkit/src/plugins/design/index.ts:28; packages/appkit/src/plugins/design/)
    Proof: On the running development fixture, GET and POST /api/design/selection both returned 404, and .appkit/design-selection.json did not exist after the browser interaction checks. Read every design plugin file: setup() returns immediately in development and only vitePlugins() contributes page serving; there is no selection schema, component/props/screenshot capture, persistence or replacement selection endpoint/MCP tool. Repository searches also found no design-selection or /api/design/selection implementation. HTTP observations are saved in checks.txt.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch 3 times, most recently from adfa702 to b5f6314 Compare October 28, 2026 09:44
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 14 · Fail · 1 critical, 2 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The change does not meet the full task: the required element selection and persistent agent handoff are absent. Design page rendering, navigation and production 404s work; 83 targeted tests pass and both changed TypeScript packages typecheck. Browser testing also reproduced false readiness after a render error and a broken route for pages/index.tsx.

Required

  • critical: The required element-selection and persistent agent-handoff workflow is missing. (packages/appkit/src/plugins/design/index.ts:64 and packages/appkit/src/plugins/design/vite-plugin.ts:128)
    Proof: Ran the real server()+design() source in Chromium on /design and the running app at /. Clicking the shared component invokes its ordinary action; there are no picker, multi-select, note or send controls. GET and POST /api/design/selection both return 404, and .appkit/design-selection.json is absent. Source inspection confirms that only page rendering/readiness and existing data-source attributes remain: no component/props/screenshot selection capture, selection store, or agent pull endpoint/tool exists. Commit 1f915cc explicitly removed these implementations. See checks.txt and working-design
  • major: A hot edit that fails to render still marks the design ready and notifies the builder. (packages/appkit/src/plugins/design/vite-plugin.ts:175)
    Proof: After a successful initial paint in a cross-origin builder iframe, edited the temporary DesignPage to throw during render. Chromium displayed Unexpected Application Error! and Review: render failed after hot edit, while GET /design/__status returned ready:true and the builder received a fresh appkit:design-ready message for index. The vite:afterUpdate handler reports the stale current page without checking whether rendering succeeded. See broken-readiness.png, checks.txt and review-session.webm.
  • major: The advertised /design/index page fails when its file is pages/index.tsx. (packages/appkit/src/plugins/design/vite-plugin.ts:135 and packages/appkit/src/plugins/design/vite-plugin.ts:193)
    Proof: Added a valid client/src/design/pages/index.tsx beside the root design/index.tsx. GET /design/__status listed both /design and /design/index. Opening /design/index returned HTTP 200 but Chromium rendered React Router’s 404 Not Found error screen. The generated router maps both files to / instead of creating /index. See broken-index-route.png and checks.txt.

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from b5f6314 to 48d89da Compare October 28, 2026 10:22
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 15 · Fail · 1 critical, 1 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The required selection and persistent agent-handoff workflow is still missing. The render-error fix works for edits to the index page, but readiness remains incorrectly true when an imported component fails after a hot edit. F20 is fixed, and all 49 focused design and server tests pass.

Required

  • critical: The required element-selection and persistent agent-handoff workflow is still missing. (packages/appkit/src/plugins/design/index.ts:64; packages/appkit/src/plugins/design/vite-plugin.ts:148 and :296)
    Proof: Read the complete design implementation and traced the existing source-location plugin: it renders pages, adds native-element data-source attributes, and exposes readiness only. Repository search for design-selection/designSelection across packages, apps, template and tools returned no matches. In Chrome, clicking and shift-clicking elements on both /design and the running app only activated the ordinary component action; no selection/note UI appeared and no .appkit/design-selection.json was created. There is no component/props/screenshot/note collection, persistent selection store, or agent p
  • major: A failing hot edit to an imported component still leaves /design marked ready. (packages/appkit/src/plugins/design/vite-plugin.ts:95-116 and :181-199)
    Proof: In the cross-origin Chrome fixture, first rendered /design successfully, then changed only client/src/components/OrderCard.tsx to throw during render. The error boundary displayed "Design page failed to render: Review: shared card hot edit failed", while GET /design/__status continued returning ready:true. Ready-message count stayed at 5, so the message suppression works but the endpoint remains stale. Reproduced without react-router as well (ready:true, message count unchanged at 3). designStatus tracks only index.tsx mtime, and the error boundary never invalidates server readiness. Direct in

@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from 0341ad5 to 2d7a963 Compare October 28, 2026 18:32
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 20 · Pass · 1 minor, 1 trivial

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

Taking the human's later scope decisions into account (selection handling moved to the builder's inspector, drafts served with a hydrator), the branch does what was asked: /design is dev-only and returns 404 otherwise, drafts render real appkit-ui blocks, errors are reported, the props schema is published, and the ui-only template is generated. All 67 design-plugin tests and the use-design-ready tests pass. One edge case is left: the dark-mode token sync follows the system color scheme and ignores a draft that forces its own theme.

Not required (below the gate)

  • minor: The chart theme tokens copied to the draft root always come from a probe element with no theme class, so a draft that forces a theme with or class="light" still gets the system's theme for its charts. (packages/appkit/src/plugins/design/drafts.ts:539-559)
    Proof: Read the code: the probe
    never takes the document's .dark/.light class, and appkit-ui's globals.css picks its theme with .dark and :root:not(.light), so the probe resolves the theme from prefers-color-scheme alone. Not exercised in a browser.
  • trivial: The original requirements for click-to-select, .appkit/design-selection.json and handing selections to the agent were removed on purpose in bbf5db8, following later decisions from the coordinator and the human; noted so the reviewer of the PR knows the task text and the branch differ. (commit bbf5db8d, said-by.jsonl coordinator messages)
    Proof: git log body of bbf5db8; coordinator 'New decisions from the human' messages

@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 21 · Fail · 1 major

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

This round's additions (browserless status fields, theme.css, shipped schema, chart data types, template vitest inline) are in place and the design and chart tests pass. One claim is overstated: compiled only transforms the index file, so a syntax error in a component the index imports still reports compiled: true and waitingFor: "paint", and an agent waiting without a browser would wait forever.

Required

  • major: compiled in /design/__status only transforms the index module, so a broken imported component reports compiled: true / waitingFor: "paint" instead of "compile" with an error, contrary to the claim that the page and its imports build. (packages/appkit/src/plugins/design/vite-plugin.ts:594-606)
    Proof: Real Vite server, same transformRequest call: index.tsx importing ./Bad (Bad.tsx = const x = {;) gives index OK, Bad.tsx ERR Unexpected token. See compiled-misses-broken-import.txt. The unit test mocks transformRequest, so it can't catch this.

- design() plugin (beta): in development serves a /design canvas that
  renders every PascalCase export under client/src/design/, and injects a
  click-to-select picker into the canvas and every app page. Picks are traced
  via the existing data-source transform plus the React fiber (component,
  owner stack, props), screenshotted, and persisted with an optional note to
  .appkit/design-selection.json (GET/POST/DELETE /api/design/selection).
  Outside development it mounts nothing and /design returns 404.
- Plugins can contribute dev-server Vite plugins via an optional
  vitePlugins() hook.
- appkit-ui/react/beta: DesignCanvas, DesignPicker, mountDesignPicker.
- Template: gated client/src/design example, .appkit/ gitignored, and a
  ui-only app template (server + design).

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
MarioCadenas and others added 16 commits October 29, 2026 17:59
- The canvas header (with the Select toggle) now stays clickable over an
  open modal and doesn't count as an outside press, using the same guard as
  the picker; Alt+S also toggles selecting from the keyboard. Open a dialog,
  then turn on Select to pick its contents.
- Picking a shape inside an icon (<path>, <circle>, ...) screenshots its
  owning <svg>; the shape alone rendered blank outside it.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
- While selecting, Escape is consumed at window capture so it no longer also
  closes an open dialog (whose contents were just picked).
- The screenshot is taken when an element is picked rather than at send, so
  a pick whose element has since left the page (a closed dialog, a
  re-render) is still sent with its image.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…s only

- /design renders the default export of client/src/design/index.tsx, and
  /design/<name> renders client/src/design/pages/<name>.tsx, at full size
  with the app's styles. Anything else under /design is a 404; in
  production /design is a 404 as before.
- Remove the canvas grid, the element picker, the selection store
  (.appkit/design-selection.json and screenshots), the /api/design routes,
  builderOrigin and the postMessage handoff, plus the react/design subpath
  of appkit-ui. Selection now belongs to the app builder's own inspector,
  which reads the dev server's data-source file:line attributes (kept).
- Template: the design sample is now client/src/design/index.tsx. Docs and
  tests updated; bundle baseline refreshed.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
Each /design page gets its own entry that imports just that page file,
instead of eagerly importing every page and picking one. An unfinished draft
in client/src/design/pages no longer breaks /design or the other pages; it
only fails at its own /design/<name>.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
The App Builder writes .appkit/data-plan.json into the app; keep that
directory out of the app's git history.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…ages

The template's theme tokens already follow prefers-color-scheme. Declaring
color-scheme "light dark" in the template's index.html and the /design
page shell makes the browser's own surfaces (canvas, scrollbars, form
controls, first paint) follow the system preference too, so the app,
/design and other surfaces match.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
- GET /design/__status returns { ready, pages }. Ready means
  client/src/design/index.tsx exists, isn't the template placeholder
  (`export const designPlaceholder = true`), and has painted since it last
  changed; the page reports its paint back after first paint and each hot
  update.
- After first paint, unless it's the placeholder, the page posts
  { type: "appkit:design-ready", version: 1, page, pages } to window.parent
  (else window.opener), only to the new builderOrigin option (bare origins,
  "*" rejected).
- With react-router (the app template ships it) design pages share a router
  with basename /design, so links stay inside /design; the requested page is
  imported directly and the others load only when navigated to.
- Template starter page carries the placeholder marker; docs and tests
  updated.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…age names

- A design page now renders inside its own error boundary, and readiness is
  reported only from a successful render; a hot edit that throws shows the
  error and leaves /design not ready (the file changed, no good paint).
- pages/index.tsx and pages/__*.tsx are no longer routed or listed:
  'index' collided with the root page in the router, and '__' prefixes the
  plugin's own /design/__status endpoint.
- The page entry's virtual id ends in .mjs so the React plugin doesn't
  inject Fast Refresh code that imports it by id.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…to render

The page's error boundary now reports a caught render error to
/design/__status, which clears the recorded paint. Readiness used to track
only index.tsx's mtime, so a broken edit to an imported component left it
ready.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
- Readiness now waits, after a successful render, for web fonts, no Suspense
  fallback on screen, no page fetch in flight, a 300 ms quiet DOM window and
  two frames; automatic waits are capped at 10 s. A fetch finishing or a
  Suspense reveal restarts the quiet window, so data that arrives and then
  renders (a chart's bars) is included. Never while the placeholder or an
  error is showing.
- New useDesignReady(ready) in @databricks/appkit-ui/react/beta holds
  readiness back explicitly (no time limit) for content the page can't
  detect; a no-op outside /design.
- Docs, tests and the template starter comment updated.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
- In development, with builderOrigin set, the design plugin adds a small
  script to the app's own pages (not /design). Once a page has settled (the
  same waits as design readiness, including useDesignReady), and again after
  client-side navigation and hot updates, it posts
  { type: "appkit:app-ready", version: 1, path } to the embedding builder,
  never while an element with data-appkit-template-home is on screen.
- The app template's default HomePage carries data-appkit-template-home, so
  a builder can also recognize it directly.
- The settle logic is shared between the design entry and the app script.
- Docs and tests updated.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…ppkit-ui

- In development the design plugin serves drafts/<name>.html at
  /design/drafts/<name>, streamed while the file is still being written
  (ends at </html> or after 8 s unchanged); editing a finished draft reloads
  it, without needless reloads for content already streamed.
- One hydrator is injected into every draft: it renders each
  <script type="application/json" data-appkit="..."> block with the real
  appkit-ui component as soon as its JSON is complete (MutationObserver +
  JSON.parse), in a shadow root styled with the app's CSS; no CDN, no
  network. Allowlist: BarChart, LineChart, AreaChart, PieChart, DonutChart
  (compact {x, series} or native chart props), DataTable (Table
  primitives), KpiCard (Card parts).
- A block that can't render shows a "Couldn't render" placeholder and is
  reported in GET /design/__status (drafts[].errors, per draft version) and
  as appkit:draft-error v1 to the builder origins.
- design-ready / app-ready unchanged. Docs, tests and template README.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…k schema

- Draft blocks got light theme tokens in dark mode: :root:not(.light) was
  rewritten to :host:not(.light), which never matches in a shadow root, so
  charts drew dark legend text on dark drafts. It now becomes
  :host(:not(.light)). The resolved tokens are also copied to the draft's
  root at the lowest priority (:where(:root)), where appkit-ui charts read
  them, and re-synced when the system scheme changes.
- The hydrator core is now runHydrator(), embedded via toString() like
  normalizeBlock; jsdom tests run it and assert the appkit:draft-error v1
  messages (builder origin only), the /design/__status POSTs and the
  placeholders; middleware tests assert GET /design/__status lists them per
  draft version. A __name shim keeps the embedded code working when the
  server runs under tsx.
- JSON Schema of every allowed data-appkit component, with examples, at
  GET /design/__data-appkit.schema.json (linked from /design/__status as
  blockSchema); tests keep it in sync with normalizeBlock. Docs list the
  exact required and optional props.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…arams

date_format(ts, "yyyy-MM-dd'T'HH:mm:ss") was read as parameters :mm and
:ss: the type generator only protected single-quoted literals and comments,
and the analytics runtime used a bare /:(\w+)/ regex. Both now share one
extractor (utils/sql-parameters.ts) that skips single- and double-quoted
literals (with '' / "" / backslash escapes), backtick identifiers, line
comments and :: casts.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…ped block schema

- /design/__status: `ready` still requires a browser to paint /design
  (documented); new `compiled` (the index page and its imports build,
  checked server-side via transformRequest), `compileError`, `waitingFor`
  ("index" | "placeholder" | "compile" | "paint" | null) and `placeholder`,
  so an agent can wait without a browser.
- /design/drafts/theme.css: the template's theme tokens (appkit-ui CSS
  variables, light and dark via prefers-color-scheme, plus .dark) and
  zero-specificity body colors, for drafts to link instead of inlining.
- The data-appkit props schema (one example per component) ships as
  @databricks/appkit-ui/design/components.schema.json, generated by
  tools/generate-design-schema.ts; a test fails when it drifts.
- appkit-ui: chart `data` accepts interface-typed and readonly rows
  (ChartDataInput), and a ChartRow type with an index signature is exported.
- Template vitest inlines @databricks/appkit-ui and echarts-for-react, whose
  extensionless ESM imports Node can't load, so chart imports work in tests.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
transformRequest only compiles the module it's given, so a syntax error in a
component the index imports still reported compiled: true and waitingFor:
"paint". The status now compiles the index and every app module it imports,
transitively (node_modules and virtual modules skipped), and compileError
names the failing module. Tested against a real Vite dev server.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
@MarioCadenas
MarioCadenas force-pushed the work/1-design-plugin-dev-only-design- branch from 88f8350 to 407f007 Compare October 29, 2026 17:00
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 22 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

F23 is fixed. compileGraph now runs transformRequest on the index module and then walks the module graph breadth-first, transforming every local script import. It skips node_modules and virtual modules, stops at 500 modules, and names the failing file. The new tests run against a real Vite server and pass, and nothing else in the design suite broke.

No findings.

MarioCadenas and others added 2 commits October 29, 2026 22:23
Charts rendered at a fixed 300px by default and overflowed shorter cards.
Without a height prop a chart now fills its parent's height (height: 100%)
with a 160px minimum for parents sized by their content; an explicit height
still sets an exact size. Applies to the chart, its wrapper and the
loading / waiting states. Docs and tests (including jsdom sizing checks).

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…and a stable URL

- Hydrator: a data-appkit block still streaming in shows a skeleton (sized by
  kind), replaced in place by the rendered component with a 200 ms fade-in;
  both off with prefers-reduced-motion.
- /design/drafts/__hydrator.js?draft=<name> is a stable URL for the
  hydrator, and /design/drafts/theme.css for the theme, so an app builder can
  include them in drafts it streams itself. Both are listed in
  /design/__status. The plugin's endpoints and Vite's module CORS allow the
  configured builderOrigin; the hydrator posts to its own origin (not via
  new URL(path, import.meta.url), which Vite rewrites to /@fs/...), and
  errors of drafts without a file are listed as streamed drafts.
- Fix: react-router for /design pages is detected with Vite's resolver and
  must be 7+; Node's require.resolve could find a hoisted react-router@5 and
  the page then never rendered.
- Docs and tests (incl. a parse check of the generated hydrator).

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 24 · Fail · 1 major

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

The design plugin code in this round holds up: the 82 design tests pass, including the streaming, skeleton and hydrator-parse tests, and the workspace typecheck is clean. But the browser demo handed to the human does not render. Its hand-written Vite server leaves out appkit-ui's @/js alias, so every component import fails with a Vite error overlay, and the agent says it never opened the page in a browser.

Required

  • major: The streaming demo given to the human shows a Vite error overlay instead of the dashboard, so the claimed browser behaviour (skeleton, then fade-in, then chart and table) has not been shown. (/tmp/stream-demo/serve.ts (outside the repo): createServer with configFile:false and root packages/appkit-ui)
    Proof: Ran write.ts, then loaded http://localhost:5199/design/drafts/demo in headless Chrome with Playwright. The page logged 500s and 'Failed to fetch dynamically imported module /src/react/index.ts', and the overlay said 'Failed to resolve import "@/js" from packages/appkit-ui/src/react/hooks/use-serving-stream.ts' (see stream-done.png). The raw JSON blocks stay on the page unhydrated. The cause is the demo's config, not drafts.ts, but the claim still has no browser proof.

The drafts folder was added to Vite's watcher. A changed .html file matches
no module, so Vite sent a full reload, and in middleware mode (how the server
plugin runs Vite) that reloads every open page on each write: a draft
mid-stream restarted and the app reloaded too. Drafts are now watched with
fs.watch, and only the appkit:draft-changed notice is sent.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 25 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

F24 is fixed. The streaming demo at localhost:5199 now shows the full Trips dashboard (KPI cards, bar chart, table), with no Vite error overlay, no console errors and a single page load. The tests for the draft-watcher fix pass.

No findings.

MarioCadenas and others added 4 commits October 30, 2026 11:59
ECharts advances its entry animation on animation frames, which the browser
pauses in hidden or background frames, such as a builder's preview. The axes
and labels were drawn while the series stayed frozen part-drawn or empty
(a blank line, a donut without its ring, a bar chart without bars). Charts
now draw their final state at once; options={{ animation: true }} turns the
animation back on.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…undle

The check for react-router 7 resolved it through Vite, which returns the
pre-bundled node_modules/.vite/deps/react-router.js. That folder's
package.json has no name, so the check failed, the page entry was built
without a router, and a page using <Link> crashed ("Cannot destructure
property 'basename'") and never painted. It now uses Node's resolution from
the design page, which finds the app's own copy.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
…, render once

- A block alone in its element fills that element's height, so an agent's
  sized box sizes the chart (it rendered at the 160px minimum). Next to a
  heading it keeps its own height and stays inside the card.
- A chart's title is a heading above the chart instead of ECharts' title,
  which was drawn over the axes and legend. The schema says to leave it out
  when the container has its own heading.
- A block that has rendered is never mounted again, also when the hydrator
  runs twice, and a block re-parsed with the same JSON doesn't fade in again.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>
@MarioCadenas

Copy link
Copy Markdown
Collaborator Author

Review 26 · Pass · 1 trivial

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

The round-17 fixes are in: charts default to animation:false and options can turn it back on, the react-router check now uses Node's resolver, and draft blocks size to their container with the title rendered as a heading. The design plugin, the ui-only template and the tests are all present, and the design and chart suites, typecheck and lint pass. I could not reproduce the hidden-iframe chart freeze in a real browser here.

Not required (below the gate)

  • trivial: Turning off chart entry animation by default changes visuals for every appkit-ui chart consumer, not only design drafts. (packages/appkit-ui/src/react/charts/base.tsx)
    Proof: git show 509a53f: default animation:false, base.test.tsx asserts it and the opt-in override

MarioCadenas and others added 2 commits October 30, 2026 12:45
This reverts commit 509a53f. With the entry animation off, the first click
on a chart was lost on the playground's metric views page (only a second
click selected the bar), failing its integration test. Frozen part-drawn
charts only stay frozen while the browser keeps animation frames paused (a
background or occluded window); they finish when frames resume.

Co-authored-by: Isaac <[email protected]>
Signed-off-by: MarioCadenas <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant