@proveanything/smartlinks 1.8.6 → 1.8.9

package/dist/api/appConfiguration.d.ts

@@ -17,9 +17,16 @@ export type AppConfigOptions = {
     batchId?: string;
     /** Item ID - required for getDataItem/deleteDataItem */
     itemId?: string;
-    /** Use admin endpoints instead of public */
+    /**
+     * Use admin endpoints instead of public.
+     * This selects which endpoint is called; it does not by itself make root-level config fields private.
+     */
     admin?: boolean;
-    /** Configuration object for setConfig */
+    /**
+     * Configuration object for setConfig.
+     * For admin-only values in app config, store them under a top-level `admin` object.
+     * Public reads return the root config but omit `config.admin`.
+     */
     config?: any;
     /** Data object for setDataItem. Best for small keyed scoped documents rather than richer app domain objects. */
     data?: any;
@@ -152,6 +159,8 @@ export declare namespace userAppData {
 /**
  * Collection/Product-scoped app configuration.
  * This is admin-managed configuration that applies to all users within the scope.
+ * Root-level config fields are typically part of the public view; if you need admin-only
+ * values, store them under a top-level `admin` object so public reads can omit them.
  *
  * @example
  * ```typescript
@@ -180,7 +189,10 @@ export declare namespace userAppData {
  */
 export declare namespace appConfiguration {
     /**
-     * Get app configuration for a collection/product scope.
+    * Get app configuration for a collection/product scope.
+    * Public reads return the public view of the config. If the stored config contains a
+    * top-level `admin` object, that block is omitted from public responses and included
+    * when `opts.admin === true`.
      *
      * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
      * @returns The configuration object
@@ -228,8 +240,10 @@ export declare namespace appConfiguration {
      */
     function listWidgetInstances(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>): Promise<WidgetInstanceSummary[]>;
     /**
-     * Set app configuration for a collection/product scope.
-     * Requires admin authentication.
+    * Set app configuration for a collection/product scope.
+    * Requires admin authentication.
+    * Writing through the admin endpoint does not make every root-level field private.
+    * Use `config.admin` for confidential values that should only be returned on admin reads.
      *
      * @param opts - Configuration options including appId, scope, and config data
      * @returns The saved configuration

package/dist/api/appConfiguration.js

@@ -200,6 +200,8 @@ export var userAppData;
 /**
  * Collection/Product-scoped app configuration.
  * This is admin-managed configuration that applies to all users within the scope.
+ * Root-level config fields are typically part of the public view; if you need admin-only
+ * values, store them under a top-level `admin` object so public reads can omit them.
  *
  * @example
  * ```typescript
@@ -229,7 +231,10 @@ export var userAppData;
 export var appConfiguration;
 (function (appConfiguration) {
     /**
-     * Get app configuration for a collection/product scope.
+    * Get app configuration for a collection/product scope.
+    * Public reads return the public view of the config. If the stored config contains a
+    * top-level `admin` object, that block is omitted from public responses and included
+    * when `opts.admin === true`.
      *
      * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
      * @returns The configuration object
@@ -309,8 +314,10 @@ export var appConfiguration;
     }
     appConfiguration.listWidgetInstances = listWidgetInstances;
     /**
-     * Set app configuration for a collection/product scope.
-     * Requires admin authentication.
+    * Set app configuration for a collection/product scope.
+    * Requires admin authentication.
+    * Writing through the admin endpoint does not make every root-level field private.
+    * Use `config.admin` for confidential values that should only be returned on admin reads.
      *
      * @param opts - Configuration options including appId, scope, and config data
      * @returns The saved configuration

package/dist/api/collection.d.ts

@@ -22,9 +22,13 @@ export declare namespace collection {
      */
     function getShortId(shortId: string): Promise<CollectionResponse>;
     /**
-     * Retrieve a specific settings group for a collection (public endpoint).
+     * Retrieve a specific settings group for a collection.
+     * Public reads return the public view of the settings group. If the stored payload contains
+     * a top-level `admin` object, that block is omitted from public responses and included when
+     * `admin === true`.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
+     * @param admin – If true, use the admin endpoint and include the admin-only settings block
      * @returns Promise resolving to the settings object
      */
     function getSettings(collectionId: string, settingGroup: string, admin?: boolean): Promise<any>;
@@ -37,6 +41,9 @@ export declare namespace collection {
     function getAppsConfig(collectionId: string): Promise<AppsConfigResponse>;
     /**
      * Update a specific settings group for a collection (admin endpoint).
+     * This writes through the admin endpoint, but root-level fields are still part of the public
+     * settings payload. Put confidential values under `settings.admin` if they should only be
+     * returned on admin reads.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
      * @param settings – The settings payload to persist

package/dist/api/collection.js

@@ -38,9 +38,13 @@ export var collection;
     }
     collection.getShortId = getShortId;
     /**
-     * Retrieve a specific settings group for a collection (public endpoint).
+     * Retrieve a specific settings group for a collection.
+     * Public reads return the public view of the settings group. If the stored payload contains
+     * a top-level `admin` object, that block is omitted from public responses and included when
+     * `admin === true`.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
+     * @param admin – If true, use the admin endpoint and include the admin-only settings block
      * @returns Promise resolving to the settings object
      */
     async function getSettings(collectionId, settingGroup, admin) {
@@ -62,6 +66,9 @@ export var collection;
     collection.getAppsConfig = getAppsConfig;
     /**
      * Update a specific settings group for a collection (admin endpoint).
+     * This writes through the admin endpoint, but root-level fields are still part of the public
+     * settings payload. Put confidential values under `settings.admin` if they should only be
+     * returned on admin reads.
      * @param collectionId – Identifier of the collection
      * @param settingGroup – The settings group name
      * @param settings – The settings payload to persist

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.6  |  Generated: 2026-03-17T21:25:13.155Z
+Version: 1.8.9  |  Generated: 2026-03-19T15:02:36.521Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,16 @@ When you need flexible app-specific data, choose the storage model based on shap
 
 Rule of thumb: if you are modelling a real domain object that users will browse, filter, secure, or evolve over time, start with app objects. If you just need a simple keyed payload hanging off a collection or product, scoped data items are still a good fit.
 
+## Settings Visibility
+
+For `appConfiguration` config blobs and `collection` settings groups, keep endpoint choice separate from visibility semantics.
+
+- **`admin: true` means "use the admin endpoint"** for reads or writes.
+- **It does not make every root field private.** Writing through an admin endpoint still saves the normal shared payload.
+- **Root-level fields are the public/shared settings view.** Put public labels, colors, toggles, and general config there.
+- **Use a top-level `admin` object for confidential values.** Public reads omit that block; admin reads include it.
+- **Applies to both** `appConfiguration.getConfig` / `setConfig` **and** `collection.getSettings` / `updateSettings`.
+
 ## API Namespaces
 
 The Smartlinks SDK is organized into the following namespaces:
@@ -5834,10 +5844,17 @@ type AppConfigOptions = {
   /** Item ID - required for getDataItem/deleteDataItem */
   itemId?: string
   
-  /** Use admin endpoints instead of public */
+  /**
+   * Use admin endpoints instead of public.
+   * This selects which endpoint is called; it does not by itself make root-level config fields private.
+   */
   admin?: boolean
   
-  /** Configuration object for setConfig */
+  /**
+   * Configuration object for setConfig.
+   * For admin-only values in app config, store them under a top-level `admin` object.
+   * Public reads return the root config but omit `config.admin`.
+   */
   config?: any
   /** Data object for setDataItem. Best for small keyed scoped documents rather than richer app domain objects. */
   data?: any
@@ -6130,7 +6147,7 @@ Get aggregate statistics for threads POST /threads/aggregate
 Scoped config and keyed data items for collections, products, variants, or batches. Best for settings and small standalone documents, not as the default answer for every app-owned entity.
 
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
-Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
+Get app configuration for a collection/product scope. Public reads return the public view of the config. If the stored config contains a top-level `admin` object, that block is omitted from public responses and included when `opts.admin === true`. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
 **getWidgetInstance**(opts: GetWidgetInstanceOptions) → `Promise<WidgetInstance<TWidget>>`
 Resolve a configured widget instance by ID from an app's stored config. This is a thin convenience wrapper over `getConfig()` that reads `config.widgets[widgetId]`. ```typescript const widget = await appConfiguration.getWidgetInstance({ collectionId: 'my-collection', appId: 'widget-toolkit', widgetId: 'launch-countdown' }) ```
@@ -6139,7 +6156,7 @@ Resolve a configured widget instance by ID from an app's stored config. This is
 List configured widget instances for an app. Useful for picker UIs, setup schemas, and widget-to-widget references. ```typescript const widgets = await appConfiguration.listWidgetInstances({ collectionId: 'my-collection', appId: 'widget-toolkit' }) ```
 
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
-Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
+Set app configuration for a collection/product scope. Requires admin authentication. Writing through the admin endpoint does not make every root-level field private. Use `config.admin` for confidential values that should only be returned on admin reads. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 
 **deleteConfig**(opts: AppConfigOptions) → `Promise<void>`
 Delete app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.deleteConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true }); ```
@@ -6614,13 +6631,13 @@ Retrieves all Collections.
 Retrieve a collection by its shortId (public endpoint).
 
 **getSettings**(collectionId: string, settingGroup: string, admin?: boolean) → `Promise<any>`
-Retrieve a specific settings group for a collection (public endpoint).
+Retrieve a specific settings group for a collection. Public reads return the public view of the settings group. If the stored payload contains a top-level `admin` object, that block is omitted from public responses and included when `admin === true`.
 
 **getAppsConfig**(collectionId: string) → `Promise<AppsConfigResponse>`
 Retrieve all configured app module definitions for a collection (public endpoint).
 
 **updateSettings**(collectionId: string, settingGroup: string, settings: any) → `Promise<any>`
-Update a specific settings group for a collection (admin endpoint).
+Update a specific settings group for a collection (admin endpoint). This writes through the admin endpoint, but root-level fields are still part of the public settings payload. Put confidential values under `settings.admin` if they should only be returned on admin reads.
 
 **create**(data: CollectionCreateRequest) → `Promise<CollectionResponse>`
 Create a new collection (admin only).

package/dist/docs/ai-guide-template.md

@@ -199,6 +199,26 @@ await SL.appConfiguration.setConfig({
 });
 ```
 
+Important visibility rule for app settings:
+
+- `admin: true` means the SDK uses the admin endpoint.
+- It does not make every root field private.
+- If a value should only be visible to admins, put it under `config.admin`.
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    enableNotifications: true,
+    admin: {
+      apiToken: 'secret-token'
+    }
+  }
+})
+```
+
 ---
 
 ## Metrics & Analytics
@@ -228,6 +248,7 @@ await SL.appConfiguration.setConfig({
 | Issue                 | Cause                      | Fix                                                   |
 | --------------------- | -------------------------- | ----------------------------------------------------- |
 | Config save fails     | Missing `admin: true` flag | Always include `admin: true` for admin operations     |
+| Secret visible publicly | Saved secret at root level | Put confidential values under the top-level `admin` object |
 | Widget doesn't render | Missing required props     | Ensure `collectionId`, `appId`, and `SL` are provided |
 | Import skips rows     | Invalid `productId`        | Verify product IDs exist in the collection            |
 | Theme not applied     | Missing `?theme=` param    | Check URL parameters or postMessage setup             |

package/dist/docs/app-data-storage.md

@@ -104,6 +104,49 @@ This data is scoped to specific collections, products, variants, or batches. It'
 
 If you need richer app-owned entities with querying, lifecycle, access zones, parent-child relationships, or workflow semantics, use [app-objects.md](app-objects.md) instead of forcing everything through `setDataItem`.
 
+### Critical: `admin: true` Controls the Endpoint, Not Field Privacy
+
+This is the part that often gets misunderstood by apps and AI tools:
+
+- `admin: true` means "call the admin endpoint".
+- It does **not** mean "everything I wrote is now admin-only".
+- For app config and collection settings, root-level fields are usually part of the public payload.
+- If you need confidential values, store them under a top-level `admin` object.
+- Public reads omit that `admin` block; admin reads include it.
+
+Example for app config:
+
+```typescript
+await appConfiguration.setConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true,
+  config: {
+    theme: 'gold',
+    supportEmail: 'support@example.com',
+    admin: {
+      accessToken: 'secret-token',
+      webhookSecret: 'top-secret'
+    }
+  }
+})
+
+const publicView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection'
+})
+// { theme: 'gold', supportEmail: 'support@example.com' }
+
+const adminView = await appConfiguration.getConfig({
+  appId: 'warranty-portal',
+  collectionId: 'my-collection',
+  admin: true
+})
+// { theme: 'gold', supportEmail: 'support@example.com', admin: { ... } }
+```
+
+The same visibility pattern applies to collection settings via `collection.getSettings()` / `collection.updateSettings()`.
+
 ### Use Cases
 - App-specific settings for a collection
 - Product-level configuration
@@ -178,7 +221,7 @@ await appConfiguration.setDataItem({
 | **Shared across collections?** | ✅ Yes | ❌ No | ❌ No |
 | **Requires auth?** | ✅ Yes (user token) | ✅ Yes (admin token for write) | Depends on public/admin endpoint and visibility |
 | **Querying / filtering** | Minimal | Minimal | Strong |
-| **Access control zones** | User-scoped only | Scope only | `data` / `owner` / `admin` zones |
+| **Access control zones** | User-scoped only | Root fields + reserved `admin` block for settings/config | `data` / `owner` / `admin` zones |
 | **Admin write required?** | ❌ No | ✅ Yes (for write operations) | Only for admin endpoints / admin fields |
 
 ---

package/dist/docs/building-react-components.md

@@ -0,0 +1,319 @@
+# Building React Components for SmartLinks
+
+> **Read this first** before implementing widgets or containers for the SmartLinks platform.
+
+This guide covers the fundamental concepts you need to understand to build React components that work correctly in the SmartLinks ecosystem. For implementation details, see [widgets.md](./widgets.md) and [containers.md](./containers.md).
+
+---
+
+## Table of Contents
+
+1. [Dual-Mode Rendering](#dual-mode-rendering)
+2. [The Router Contract](#the-router-contract)
+3. [The useAppContext Pattern](#the-useappcontext-pattern)
+4. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Dual-Mode Rendering
+
+Every SmartLinks component can run in **two modes**. The platform decides which mode to use based on configuration — your app doesn't choose.
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Your component runs directly in the parent's React context | Default - better performance, shared context |
+| **Iframe** | Your app runs inside an iframe with its own URL | Fallback - full isolation when needed |
+
+**Key insight:** You write your component code once, and it must work correctly in **both** modes.
+
+### What Changes Between Modes?
+
+| Aspect | Direct Component Mode | Iframe Mode |
+|--------|----------------------|-------------|
+| **Context source** | Props passed from parent | URL search parameters |
+| **Router** | Parent provides `MemoryRouter` | Your app provides `HashRouter` |
+| **Styling** | Inherits parent's CSS scope | Fully isolated CSS |
+| **SDK instance** | Shared with parent via props | Own instance from `window.SL` |
+| **Communication** | Direct callbacks (props) | `postMessage` |
+
+---
+
+## The Router Contract
+
+This is the **most important rule** to avoid runtime errors:
+
+### ❌ The Critical Rule
+
+> **Your exported component (`PublicContainer` or `PublicComponent`) must NOT be wrapped in any `<Router>` component.**
+
+If you wrap your export in `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`, React Router will throw:
+
+```
+Error: You cannot render a <Router> inside another <Router>
+```
+
+### ✅ Where Routing Goes
+
+**For Widgets (no routing needed):**
+```tsx
+// src/exports/PublicComponent.tsx
+export const PublicComponent = (props) => {
+  return <WidgetContent />; // No router needed
+};
+```
+
+**For Containers (with internal navigation):**
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+
+export const PublicContainer = (props) => {
+  return (
+    <Routes>  {/* ✅ Routes are fine */}
+      <Route path="/" element={<Home />} />
+      <Route path="/detail/:id" element={<Detail />} />
+    </Routes>
+  );
+};
+```
+
+**For Iframe Entry Point:**
+```tsx
+// src/App.tsx (only used in iframe mode)
+import { HashRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <HashRouter>  {/* ✅ HashRouter only in iframe entry point */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </HashRouter>
+  );
+}
+```
+
+### Why This Matters
+
+```
+Direct Component Mode:
+  Portal App
+    └─ MemoryRouter ← Parent provides this
+         └─ Your Component
+              └─ [If you add another Router here, it breaks]
+
+Iframe Mode:
+  <iframe>
+    └─ Your App.tsx
+         └─ HashRouter ← You provide this
+              └─ Your Component
+```
+
+---
+
+## The useAppContext Pattern
+
+To access context (collectionId, productId, etc.) in a way that works in **both** modes, use this abstraction:
+
+### The Hook
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from React Context (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // Direct-component mode
+  if (ctx) return ctx;
+  
+  // Iframe mode — read from URL
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+### Wire It Up in Your Export
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { AppContext } from '@/hooks/useAppContext';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <YourComponentTree />
+    </AppContext.Provider>
+  );
+};
+```
+
+### Use It in Your Components
+
+```tsx
+// Anywhere in your component tree
+import { useAppContext } from '@/hooks/useAppContext';
+
+function MyComponent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // This works in both direct-component and iframe modes!
+  
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+### Why Not Just useSearchParams()?
+
+In **direct-component mode**, there are no URL search params — context comes as props. If you use `useSearchParams()` directly, it will return empty values. The `useAppContext()` pattern handles both cases automatically.
+
+---
+
+## Common Pitfalls
+
+### ❌ "You cannot render a `<Router>` inside another `<Router>`"
+
+**Cause:** Your exported component wraps itself in a Router.
+
+**Fix:** Remove the Router wrapper from `PublicContainer.tsx` or `PublicComponent.tsx`. Only your iframe entry point (`App.tsx`) should have a Router.
+
+---
+
+### ❌ "Invalid hook call" / Minified React error #321
+
+**Cause:** Your bundle includes its own copy of React instead of using the parent's shared instance.
+
+**Fix:** Ensure your build configuration externalizes React, ReactDOM, and react/jsx-runtime:
+
+```ts
+// vite.config.container.ts or vite.config.widget.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react-router-dom',
+        '@proveanything/smartlinks',
+        // ... other shared dependencies
+      ],
+    },
+  },
+});
+```
+
+---
+
+### ❌ Context values are undefined in direct-component mode
+
+**Cause:** Using `useSearchParams()` or reading from `window.location` instead of using the `useAppContext()` pattern.
+
+**Fix:** Implement the `useAppContext()` hook as shown above and use it throughout your component tree.
+
+---
+
+### ❌ Navigation doesn't work
+
+**Cause:** Using `window.location` or `window.parent.postMessage` for navigation.
+
+**Fix:** Use the `onNavigate` callback from props/context with structured `NavigationRequest` objects. See [widgets.md](./widgets.md#cross-app-navigation) for details.
+
+---
+
+### ❌ Styles leak between apps
+
+**Cause:** Direct components share the parent's CSS scope — there's no iframe isolation.
+
+**Fix:** Use CSS Modules, scoped class prefixes, or Tailwind with a unique prefix. Avoid global CSS selectors in your bundle.
+
+---
+
+### ❌ CORS errors when loading bundles
+
+**Cause:** Your widget/container JavaScript or CSS is served from a different origin without CORS headers.
+
+**Fix:** Configure CORS headers on your hosting, or use inline bundle source via the SDK's `getWidgets()` API.
+
+---
+
+## Quick Diagnostic Checklist
+
+| Issue | Check |
+|-------|-------|
+| Router error | Remove all `<Router>` wrappers from your exported component |
+| Invalid hook call | Verify React is externalized in your build config |
+| Missing context | Use `useAppContext()` instead of `useSearchParams()` |
+| Duplicate React | Check `window.React === yourBundle.React` in browser console |
+| CSS conflicts | Use scoped CSS (modules/prefixes), avoid global selectors |
+
+---
+
+## File Structure Reference
+
+```
+my-app/
+├── src/
+│   ├── App.tsx                     ← Iframe entry (has HashRouter)
+│   ├── exports/
+│   │   ├── PublicContainer.tsx     ← Container export (no Router!)
+│   │   └── PublicComponent.tsx     ← Widget export (no Router!)
+│   ├── hooks/
+│   │   └── useAppContext.ts        ← Dual-mode abstraction
+│   ├── pages/
+│   │   ├── Home.tsx                ← Shared components
+│   │   └── Detail.tsx
+│   └── main.tsx                    ← Iframe bootstrap
+├── vite.config.ts                  ← Iframe build
+├── vite.config.container.ts        ← Container bundle
+└── vite.config.widget.ts           ← Widget bundle
+```
+
+---
+
+## Next Steps
+
+Now that you understand the core concepts, see the implementation guides:
+
+- **[widgets.md](./widgets.md)** — Build lightweight preview components
+- **[containers.md](./containers.md)** — Build full-page embedded experiences
+- **[mpa.md](./mpa.md)** — Multi-page app architecture (optional)
+- **[iframe-responder.md](./iframe-responder.md)** — Parent-side iframe integration
+
+---
+
+## Related Documentation
+
+- [theme.system.md](./theme.system.md) — Theming and CSS variables
+- [ai.md](./ai.md) — AI assistant integration
+- [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
+- [manifests.md](./manifests.md) — App manifest configuration