@fayz-ai/app-builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faya Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @fayz-ai/app-builder
+
+> **Status: preview (experimental).** The surface is real; the code view, publish and chat are contracts with minimal implementations. API may change without notice.
+
+> The app-builder surface: a window bar, the app running inside it, and the seams for seeing the code, publishing, and talking to whoever is doing the work.
+
+[![npm](https://img.shields.io/npm/v/@fayz-ai/app-builder.svg)](https://www.npmjs.com/package/@fayz-ai/app-builder)
+[![license](https://img.shields.io/npm/l/@fayz-ai/app-builder.svg)](https://github.com/FayaLabs/fayz-sdk/blob/main/LICENSE)
+
+The Fayz editor and an admin app need the same thing: the window chrome, the live app inside it, the conversation beside it, and a publish button. Writing that twice is the mistake this package exists to avoid. One surface, two hosts — the editor keeps its container lifecycle and its chat, the admin keeps its shell and its assistant, and both mount the same component.
+
+## Two doors
+
+- **`.`** — the surface. **No `@fayz-ai/*` dependency at all**: React, lucide-react and shadcn tokens, which both hosts already have. This is the door the Fayz editor imports.
+- **`./plugin`** — `createAppBuilderPlugin()`, how the SDK admin mounts it. Pulls `@fayz-ai/core`, `@fayz-ai/admin` and `@fayz-ai/ui` as **optional** peers, so importing the surface never drags the admin in.
+
+## Install
+```bash
+npm install @fayz-ai/app-builder
+```
+Peer deps: `react`, `react-dom`, `lucide-react`. Optional peers (only for `./plugin`): `@fayz-ai/core`, `@fayz-ai/admin`, `@fayz-ai/ui`.
+
+## The surface
+```tsx
+import { AppBuilder } from '@fayz-ai/app-builder'
+
+<AppBuilder
+  target={{ name: 'Artorius', url: containerPreviewUrl, liveUrl }}
+  chat={<YourChatColumn />}
+  chatContract={{ send: (message, element) => yourChat.send(message, element) }}
+  publish={{ state, publish }}
+  onClose={goBack}
+  onToggleChat={toggleChat}
+  onToggleWide={toggleSidebar}
+  slots={{ chromeEnd: <YourTabs />, belowCanvas: <YourTerminal /> }}
+/>
+```
+
+Preview and code are **one surface in two states** (`mode`), not two components: pass a `code` slot and the switch appears; omit it and it does not exist. The chat is never drawn here — it varies per host — but `chatContract` is how "change this block" gets from the canvas into whatever conversation the host mounted. `publish` is the same button in both hosts with each one's transport behind it; without a contract it renders disabled and says why.
+
+## The admin
+```tsx
+import { createAppBuilderPlugin } from '@fayz-ai/app-builder/plugin'
+
+plugins: [createAppBuilderPlugin({ sandboxUrl: import.meta.env.VITE_APP_BUILDER_SANDBOX_URL })]
+```
+Mounts an `immersive` route (no nav entry — the door is the "Seu site" widget), resolves the target from the tenant's site row, opens the shell's assistant rail, and publishes `builder_navigate` / `builder_reload` / `builder_set_viewport` / `builder_request_change` to the agent.
+
+## Part of the Fayz SDK
+Roadmap: the element-picker overlay (the protocol is already wired on both sides), a real code surface, and the Fayz editor swapping its `components/preview/` tree for this one.

package/dist/admin/AdminAppBuilder.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import type { AppBuilderPluginOptions } from './options';
+/**
+ * The admin's wiring of the surface: where the target comes from, what the
+ * window buttons do here, and which colleague is on duty. Everything in this
+ * file is host-specific — the surface itself knows none of it.
+ */
+export declare function AdminAppBuilder({ options }: {
+    options?: AppBuilderPluginOptions;
+}): React.JSX.Element;
+//# sourceMappingURL=AdminAppBuilder.d.ts.map

package/dist/admin/AdminAppBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdminAppBuilder.d.ts","sourceRoot":"","sources":["../../src/admin/AdminAppBuilder.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAc9B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAMxD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,CAAC,EAAE,uBAAuB,CAAA;CAAE,qBA2GjF"}

package/dist/admin/agent-surface.d.ts

@@ -0,0 +1,18 @@
+import type { BuilderTarget, BuilderViewport } from '../types';
+export interface BuilderAgentSurfaceDeps {
+    target: BuilderTarget;
+    currentPath: string;
+    viewport: BuilderViewport;
+    actions: {
+        navigate: (path: string) => void;
+        reload: () => void;
+        setViewport: (viewport: BuilderViewport) => void;
+    };
+    onRequestChange?: (input: {
+        projectId: string;
+        path: string;
+        instruction: string;
+    }) => Promise<string> | string;
+}
+export declare function useBuilderAgentSurface(deps: BuilderAgentSurfaceDeps): void;
+//# sourceMappingURL=agent-surface.d.ts.map

package/dist/admin/agent-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-surface.d.ts","sourceRoot":"","sources":["../../src/admin/agent-surface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAkC9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,aAAa,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,eAAe,CAAA;IACzB,OAAO,EAAE;QACP,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;QAChC,MAAM,EAAE,MAAM,IAAI,CAAA;QAClB,WAAW,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAA;KACjD,CAAA;IACD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;CAChH;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CA6F1E"}

package/dist/admin/options.d.ts

@@ -0,0 +1,22 @@
+import type { PluginScope, VerticalId } from '@fayz-ai/core';
+import type { BuilderLabels } from '../types';
+export interface AppBuilderPluginOptions {
+    route?: string;
+    navLabel?: string;
+    scope?: PluginScope;
+    verticalId?: VerticalId;
+    /** Address of the running preview container; else VITE_APP_BUILDER_SANDBOX_URL. */
+    sandboxUrl?: string;
+    /** Where a natural-language change request goes. Absent = not connected. */
+    onRequestChange?: (input: {
+        projectId: string;
+        path: string;
+        instruction: string;
+    }) => Promise<string> | string;
+    /** Publish what is on the canvas. Absent leaves the button disabled and honest. */
+    onPublish?: (input: {
+        projectId: string;
+    }) => Promise<void> | void;
+    labels?: BuilderLabels;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/admin/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/admin/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IAC/G,mFAAmF;IACnF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAClE,MAAM,CAAC,EAAE,aAAa,CAAA;CACvB"}

package/dist/admin/target.d.ts

@@ -0,0 +1,20 @@
+import type { BuilderTarget } from '../types';
+export interface AdminTargetOptions {
+    /** Address of the running preview container, when the host knows it. */
+    sandboxUrl?: string;
+}
+/**
+ * The tenant's default site row, as a builder target.
+ *
+ * The canvas is THE APP — the running preview container — never the platform's
+ * editor: embedding the editor would put its chat inside ours and hand the
+ * merchant two conversations for one question. With no sandbox address known it
+ * falls back to the published site, which is still the app, just yesterday's.
+ */
+export interface AdminTargetState {
+    target: BuilderTarget | null;
+    /** The tenant's projects have not answered yet — "none" is not the answer. */
+    loading: boolean;
+}
+export declare function useAdminBuilderTarget(options?: AdminTargetOptions): AdminTargetState;
+//# sourceMappingURL=target.d.ts.map

package/dist/admin/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../src/admin/target.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAC5B,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,CA8BpF"}