[edcheung1]

What did you change, and why?

Why: Let authors publish a Lakeflow Designer flow as a Databricks App where users supply inputs, run the flow, and inspect its results. Maintain the shared server runtime as an installable designer() source plugin in appkit-registry.

Change: Adds the complete appkit-lakeflow-designer template: a React/AppKit UI, the installed Designer server plugin, deployment configuration, documentation, and tests. Designer provisions each App with its own Workspace manifest and runner Job. This PR includes the template introduced in #267 and targets main directly; it does not require that PR to merge first.

Published App behavior

• Inputs and runs: Text, number, dropdown, combobox, multi-select, and file parameters; non-file input restoration, run history, cancellation, and status. File inputs must be selected before Run is enabled. Dropdown and multi-select choices are validated allowlists; combobox choices are suggestions.
• Results: Tables use TanStack sorting, search, column visibility/resizing, and sticky headers, without pagination. Previews show up to 1,000 rows and distinguish complete, truncated, and unknown-completeness results. Charts use Vega-Lite/Vega, with a table fallback for unsupported specifications. Guardrails warnings and failures remain associated with the displayed run.
• Visibility: Individual output and Markdown blocks can stay hidden until results exist. Outputs disabled by their operator or parent group are hidden using published configuration and recorded runtime state. Spark evaluates expression-based conditions during the run; changing a parameter alone does not evaluate them in the browser.
• Files: File parameters upload to configured UC storage and remain downloadable from run parameter summaries. File Output operators provide CSV, JSON, and XLSX downloads, with a searchable selector for multiple files. Storage paths stay hidden. Downloads stream recorded files without rerunning the Job; overwrite artifacts are isolated per execution, while shared append/workbook downloads return the destination's current contents.
• Recovery: The UI retains accepted runs through temporary status failures and preserves previous results during a rerun. An Apps gateway startup response triggers one guarded page reload to recover from idle compute. Recovery never automatically resubmits a Job.
• HTML and Markdown: Render authored Markdown and HTML results. HTML runs with inline scripts in an opaque-origin sandbox inside a trusted wrapper; CSP restricts external resources and navigation, and the message bridge accepts bounded resize/error information. The iframe grows and shrinks with interactive content between 160 and 1,600 px, including when selections are cleared.

Published App server and registry plugin

The Node/AppKit server runs on Databricks Apps compute. One createApp() registers AppKit's server() and the local designer() plugin. The plugin owns /api/designer routes and uses the shared AppKit service client to:

• Load and validate designerApp.json beside the bound runner notebook.
• Validate parameters and runner revisions, resolve uploaded files, and submit the runner Job with verified viewer/App attribution and a parameter snapshot.
• Provide viewer-scoped history, status, cancellation, results, and downloads.
• Decode exported notebook results into bounded previews, row counts, HTML, disabled states, and Guardrails diagnostics.
• Handle parameter uploads and stream authorized parameter-file and generated-file downloads through UC storage.

The runner Job executes the DAG and Spark expressions using its configured run-as identity. The App server calls Databricks APIs as its service principal with explicitly granted permissions; hosting on Databricks supplies no implicit access to engineering infrastructure or other workspaces. App credentials remain on the server. Consumer access to runs and files is scoped to the viewer inside the App; independent Job and UC permissions remain effective outside it.

The 38 installed files in server/plugins/designer match the generated item in databricks/appkit-registry#11. Backend implementations and shared-contract tests are maintained there. Browser code imports the plugin's client-safe schemas, run/result types, response parsers, and route helpers. Manifest loading is isolated inside the plugin while preserving refresh, cache, and shutdown behavior. The template commits the installed source and records its originating registry commit in the README. Git tracks the plugin source, and pnpm-lock.yaml pins its npm dependencies. The template uses released AppKit/AppKit UI 0.89.0, pnpm 11.0.8, and Node.js 22.13+, with a frozen lockfile, dependency overrides, and a documented body-parser patch.

Publishing and compatibility

• Requires manifest v8 and the matching Designer publisher/runner. Unsupported manifest versions block submissions; there is no automatic migration or version fallback.
• Designer resolves the configured template reference to a commit and deploys a snapshot of the committed source. Publishing does not run appkit add or fetch the registry. This branch builds before the registry PR merges and requires no new SDK release. Subsequent plugin changes are installed into the template, reviewed and committed, then adopted by republishing Apps.
• The registry refactor needs no additional Universe publisher or codegen changes. Select edcheung1/app-templates@branch:stack/designer-plugin-template through the existing databricks.fe.lakebuilder.designerAppTemplateRef setting for development, or pin an approved commit/tag. Changing that setting does not update already deployed Apps; they must be republished.
• The App principal needs runner Job CAN_MANAGE and the relevant upload/output volume grants. The runner separately needs its data read/write permissions. Viewers can execute the workflow with the runner's permissions; the matching publisher asks authors to acknowledge that execution model. Security sign-off on that model and the iframe/API boundary remains open. Authored HTML requires trusted publishers and is not a complete data-loss or resource-exhaustion boundary.

Example published App

Sales Review Lab (Dogfood access required). These screenshots illustrate the UI using a synthetic demo and an existing successful run; validation of this PR's exact commit is recorded below.

Parameters, run history, and author-provided instructions.

HTML report and regional chart

Interactive table and generated-file selector

How do you know it works?

Current validation at template commit 07d2ee546531a9c0343e443964444b8c6ac4ab12:

• 148 template tests passed: parameter controls, manifests/results, downloads, tables/charts, run tracking, and restoration.
• 40 Chrome checks passed: HTML isolation/navigation, run and startup recovery, and repeated HTML expansion/collapse, including body margins and shrinking from the 1,600 px maximum to the 160 px minimum. The new collapse regression failed against the previous implementation and passed after the fix.
• Production server/client build (including typecheck), lint, and formatting checks for the changed files passed. Lint reports only the existing TanStack/React Compiler warning; the template does not enable React Compiler.
• Verified the exact NFL Games report in the signed-in browser with a temporary preview of the fixed bootstrap: selecting SF/SEA expands to 1,600 px for 53 games, and Clear returns to 712 px on repeated cycles. The deployed implementation stayed at 1,600 px after Clear. The preview was restored afterward; that App still needs republishing to adopt this commit.

Additional coverage from the preceding contract cleanup: 134 registry tests and 37 Chrome checks passed at registry 4cffd42 / template 326ce11, covering real AppKit routes and SDK HTTP/streaming paths with simulated services, shared contracts, HTML navigation restrictions, republish recovery, and idle/startup reload behavior. Lint at that revision had no errors and the existing TanStack/React Compiler warning; the template does not enable React Compiler.

Earlier local integration validation at 75f39a842ae60eef49e8d746fde0b8423d4ecb85: 15 browser e2e scenarios passed with no JavaScript errors through the compiled template, installed plugin, and released SDK transport with simulated Jobs/Workspace/Files. Covered transfers, generated-file selection, disabled groups, history, cancellation/failure, truncation totals, storage changes, restart, viewer isolation, and manifest mismatch. These scenarios were not rerun for the iframe sizing fix.

Earlier deployed e2e at 75f39a842ae60eef49e8d746fde0b8423d4ecb85: Published that template commit from the Designer UI to the dedicated staging App. Deployment 01f1d3beacef159d9ddbbdf824075f77 succeeded and switched traffic. Through real Apps ingress, /api/designer/config returned manifest v8 and runnable=true; an explicit Run started Job run 978236073796935, which completed successfully. The App rendered the 12-row table, revenue chart, and HTML report. Reload restored that run and its outputs.

This validates publish/build/load/run with the deployed App service principal's Jobs/Workspace access. File transfers, cancellation, conditional groups, and second-viewer isolation were covered locally with simulated services, not separately exercised in the deployed App.