@innovastudio/contentbox 1.6.193 → 1.6.195

package/readme.txt

@@ -1,253 +1,348 @@
-ContentBox.js 5.9.5
+========================================================================
+ CONTENTBOX.JS 6.0.0
+========================================================================
 
-Note: If you have Source Code package (Super license), please refer to:
+Thanks for using ContentBox - a browser-based drag & drop page builder.
+This package contains the ready-to-use library plus HTML, PHP, and
+JavaScript examples showing how to run and configure it.
 
-    readme-sourcecode.txt
+This file is your starting point. It covers:
 
-    for additional information.
+    1. Getting started (run the examples)
+    2. Where things live (a map of the package)
+    3. How to customize
+    4. Working with an AI assistant (Claude, etc.)
+    5. Setting up the AI features (API keys)
+    6. Registering plugins
+    7. Upgrading to a new version
+    8. Documentation & support
 
-Documentation:
+If you have the Source Code package (Super License), also see
+readme-sourcecode.txt - it covers running and editing the library source.
 
-    https://github.com/innovastudio-dev/contentbox/
 
-    https://demo.innovastudio.com/docs/ContentBox.pdf (old version)
+------------------------------------------------------------------------
+ 1. GETTING STARTED
+------------------------------------------------------------------------
 
-    https://demo.innovastudio.com/docs/AI-Assistant.pdf (AI Assistant documentation)
+You can run the HTML, PHP, or JavaScript example. All you need for the
+HTML and JavaScript ones is Node.js / npm installed:
+https://nodejs.org/en/download/
 
 
-Getting started
+A. HTML EXAMPLE
 
-You can choose to run the HTML, PHP or JavaScript project examples:
+    1. Unzip the package (folder: ContentBox/)
 
-A. To try the HTML example:
+    2. From a terminal, in the project folder, install the server
+       dependencies (the example uses a Node.js server):
 
-    1. Unzip the project files:
+           > cd ContentBox
+           > npm install
 
-       - ContentBox/
+    3. Create your .env file from the template and add your API keys:
 
-    2. Open terminal, go to the project directory and install the required server dependencies.
-       The example is using Node.js server.
+           > cp .env.example .env
 
-        > cd ContentBox
+       The .env file holds your API keys and is excluded from version
+       control (.gitignore). Only .env.example is committed, so never
+       put real keys in it.
 
-        > npm install
+    4. Run the server:
 
-            Note: To run this command, you need to have NPM installed.
-            Download & install NPM from https://nodejs.org/en/download/.
+           > node server.js
 
-    3. Run the server:
+    5. Open in your browser:
 
-        > node server.js
+           http://localhost:8081/example.html
 
-    4. Open from your browser:
 
-        http://localhost:8081/example.html 
+B. PHP EXAMPLE
 
+    Open in your browser:
 
-B. To try the PHP Example, open from your browser:
+           http://localhost/.../public/example.php
 
-    http://localhost/.../public/example.php
- 
-    If you're using Visual Studio Code, you can use the PHP Server extension.
+    (In VS Code, the PHP Server extension is an easy way to serve it.)
 
 
-C. To try the JavaScript project, install the dependencies and start the project:
+C. JAVASCRIPT PROJECT
 
-        > npm install
+    A small project that imports the library and configures it in code:
 
-        > npm start
+           > npm install
+           > npm start
 
-    A browser window will be opened with the example running.
+    A browser window opens with the example running. The file to look
+    at is src/index.js (see the next section). Examples for React/Next.js
+    and Laravel are also provided.
 
-    Note:
-        The code for this project is:
-            
-            src/index.js
 
-        The project is using Node.js server:
+------------------------------------------------------------------------
+ 2. WHERE THINGS LIVE
+------------------------------------------------------------------------
 
-            server.js
+    src/index.js                 The JavaScript project's code: it
+                                 imports ContentBox (from the npm
+                                 package) and configures it. This is the
+                                 best place to learn how to wire up the
+                                 builder - uploads, AI providers,
+                                 templates, plugins - as real, working
+                                 code you can copy from.
 
-NOTE:
+    public/                      Everything served in the browser:
+        example.html               The main HTML example.
+        example.php                The PHP example.
+        blank-plugins.html         Plugin registration (see section 6).
+        preview.html               Preview page (renders saved content).
+        contentbox/                The built library.
+        assets/                    Templates, snippets, plugins, fonts.
+        assets/plugins/            The plugins (one folder each).
+        api/                       PHP backend endpoints (uploads, AI).
 
-- To use the AI Assistant:
+    server.js / server-aws.js    The Node.js backend for the examples
+                                 (uploads + AI endpoints). server-aws.js
+                                 is the same thing using S3 storage.
 
-    1. Obtain the API key from OpenAI or OpenRouter
-        
-        https://openai.com
+    .env / .env.example          Your API keys for the AI features
+                                 (see section 5). Copy .env.example to
+                                 .env and fill in your keys. Needed only
+                                 if you use the AI-assisted features.
 
-        or
+    docs/                        Documentation, including the upgrade
+                                 guide.
 
-        https://openrouter.ai 
+Note: this package contains the ready-to-use library, not its source.
+If you need to change how the library itself works, that's what the
+Source Code (Super License) package is for.
 
-        Use OpenRouter if you want to use various models.
 
-    2. Update the .env file with your API key.
+------------------------------------------------------------------------
+ 3. HOW TO CUSTOMIZE
+------------------------------------------------------------------------
 
-        OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+    1. CONFIGURE WITH OPTIONS.
+       Most behavior - the sidebar, upload handlers, AI endpoints,
+       templates - is controlled by the options object passed to
+       "new ContentBox({...})". See src/index.js for a live example, and
+       docs/ for the full list of options and methods.
 
-        or
+    2. ADD FEATURES WITH PLUGINS.
+       A plugin is its own folder under public/assets/plugins/<name>/
+       (an index.js and a style.css), loaded via the "plugins" option.
+       (See section 6 for registering plugins in your own pages.) The
+       plugin docs sit right beside them:
 
-        OPENROUTER_API_KEY=YOUR_API_KEY
+           public/assets/plugins/README.md                 catalog
+           public/assets/plugins/plugin-dev-guide.md        how to build one
+           public/assets/plugins/plugin-example.md          worked example
+           public/assets/plugins/plugin-patterns.md         common patterns
+           public/assets/plugins/plugin-best-practices.md   conventions
 
-    Or if you're using PHP, update the api/config.php file with your API key:
+       They're plain Markdown, so you can hand the folder to an AI
+       assistant as reference and just describe the plugin you want.
 
-        $OPENAI_API_KEY = 'YOUR_API_KEY';
+    3. RESTYLE WITH CSS / TEMPLATES.
+       Templates live under public/assets/ and can be customized there.
+       Add your own CSS to override styles. (The SCSS theme sources, for
+       building new themes from scratch, come with the Source Code
+       package.)
 
-        or
 
-        $OPENROUTER_API_KEY = 'YOUR_API_KEY';
-        
-    3. Ensure that the sendCommandUrl parameter is set with the API endpoint:
+------------------------------------------------------------------------
+ 4. WORKING WITH AN AI ASSISTANT (CLAUDE, ETC.)
+------------------------------------------------------------------------
 
-        const builder = new ContentBox({
-            // ...
-            sendCommandUrl: '/sendcommand',
-            // sendCommandUrl: '/openrouter', // Using OpenRouter (https://openrouter.ai/)
-        });
+An AI coding assistant such as Claude Code can do a lot with this package
+alone. Point it at the project and it can read:
 
-        If you're using PHP:
+    - docs/             - the documentation (options, methods, guides),
+    - src/index.js      - a real, working configuration to follow,
+    - assets/plugins/   - the plugin API and docs.
 
-        const builder = new ContentBox({
-            // ...
-            sendCommandUrl: 'api/sendcommand.php',
-            // sendCommandUrl: '/api/openrouter.php', // Using OpenRouter (https://openrouter.ai/)
-        });
+With those in the project, it can tell you which option to set for a
+given goal, adjust your src/index.js, or build a plugin against the real
+plugin structure - grounded in the actual API rather than guesswork.
 
-        Most examples in the package have this parameter configured, so you can run and test them.
-        Examples in React/Next.js and Laravel are also provided.
+The Source Code package takes this further: with the full library source
+in your project, an assistant has the complete context to work from - so
+it builds with more confidence, and opens up a wider range of what you
+can create, grounded in how ContentBox really works.
 
-        The JavaScript project example in this package uses Node.js for the API endpoint /sendcommand.
-        Please refer to the Node.js file:
 
-            server.js
+------------------------------------------------------------------------
+ 5. SETTING UP THE AI FEATURES (API KEYS)
+------------------------------------------------------------------------
 
-    For more information, please refer to the documentation:
+The AI Assistant and AI image generation are optional. They work once
+you add API keys and point the matching options at the endpoints. Most
+examples in the package already have these options set, so they run as
+soon as the keys are in place.
 
-        https://demo.innovastudio.com/docs/AI-Assistant.pdf 
+Add your own security to the API endpoints before going to production!
 
-- For speech recognition (if dictation is enabled), the browser's built-in
-    speech recognition is used. However, certain browsers may not support this feature.
-    We recommend using Deepgram for browser compatibility and accuracy.
-    Obtain the Deepgram API key from https://deepgram.com and update the .env file with your API key.
-    Then enable the 'speechTranscribeUrl' parameter in the ContentBox initialization (src/index.js).
 
-- To use the AI image generation:
+5.1  AI ASSISTANT
 
-    - New version:
+    1. Get an API key from OpenAI or OpenRouter:
 
-        1. Obtain the API key from Fal.ai:
+           https://openai.com
+           https://openrouter.ai     (use this for access to many models)
 
-            https://fal.ai 
-            
-        2. Update the .env file with your API key.
+    2. Add it to the .env file:
 
-            FAL_API_KEY=YOUR_API_KEY
+           OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+           OPENROUTER_API_KEY=YOUR_API_KEY
 
-        Alternatively, if you're using PHP, update the 'api/config.php' file with your API key:
+       Or, for PHP, add it to api/config.php:
 
-            $FAL_API_KEY = 'YOUR_API_KEY';
+           $OPENAI_API_KEY = 'YOUR_API_KEY';
+           $OPENROUTER_API_KEY = 'YOUR_API_KEY';
 
-        3. Obtain the API key from OpenAI
-            
-            https://openai.com
+    3. Set the sendCommandUrl option to the endpoint:
 
-        4. Update the .env file with your API key.
+           const builder = new ContentBox({
+               // ...
+               sendCommandUrl: '/sendcommand',
+               // sendCommandUrl: '/openrouter',   // OpenRouter
+           });
 
-            OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+       For PHP:
 
-        Or if you're using PHP, update the api/config.php file with your API key:
+           const builder = new ContentBox({
+               // ...
+               sendCommandUrl: 'api/sendcommand.php',
+               // sendCommandUrl: '/api/openrouter.php',   // OpenRouter
+           });
 
-            $OPENAI_API_KEY = 'YOUR_API_KEY';
+    The JavaScript project serves these endpoints from server.js.
 
-        5. Ensure that the following parameters are set:
+    More detail: https://demo.innovastudio.com/docs/AI-Assistant.pdf
 
-            const builder = new ContentBox({
-                // ...
 
-                defaultImageGenerationProvider: 'fal',
-                generateMediaUrl_Fal: '/request-fal',
-                checkRequestStatusUrl_Fal: '/status-fal',
-                getResultUrl_Fal: '/result-fal',
-            });    
+5.2  SPEECH RECOGNITION (optional, for dictation)
 
-            If you're using PHP:
+    If dictation is enabled, the browser's built-in speech recognition
+    is used - but some browsers don't support it. For broader
+    compatibility and accuracy, use Deepgram: get a key from
+    https://deepgram.com, add it to .env, then enable the
+    speechTranscribeUrl option in src/index.js.
 
-            const builder = new ContentBox({
-                // ...
 
-                defaultImageGenerationProvider: 'fal',
-                generateMediaUrl_Fal: 'api/request-fal.php',
-                checkRequestStatusUrl_Fal: 'api/status-fal.php',
-                getResultUrl_Fal: 'api/result-fal.php',
-            });   
+5.3  AI IMAGE GENERATION
 
+    Current provider - Fal.ai:
 
-    - Legacy version:
+    1. Get an API key from https://fal.ai and add it to .env:
 
-        1. Obtain the API key from Getimg:
-        
-            https://getimg.ai/tools/api 
+           FAL_API_KEY=YOUR_API_KEY
 
-        2. Update the .env file with your API key.
+       (PHP: add $FAL_API_KEY = 'YOUR_API_KEY'; to api/config.php)
 
-            GETIMG_API_KEY=YOUR_API_KEY
+    2. Also add an OpenAI key (https://openai.com) to .env:
 
-        Alternatively, if you're using PHP, update the 'api/config.php' file with your API key:
+           OPENAI_API_KEY=YOUR_OPENAI_API_KEY
 
-            $GETIMG_API_KEY = 'YOUR_API_KEY';
+       (PHP: $OPENAI_API_KEY = 'YOUR_API_KEY'; in api/config.php)
 
-        3. Ensure that the following parameters are set:
+    3. Set these options:
 
-            const builder = new ContentBox({
-                // ...
-                    
-                textToImageUrl: '/texttoimage', 
-                upscaleImageUrl: '/upscaleimage',
-                imageModel: 'flux-schnell',
-                imageAutoUpscale: false,
-                // viewFileUrl: '/viewfile', // If using S3
-            });
+           const builder = new ContentBox({
+               // ...
+               defaultImageGenerationProvider: 'fal',
+               generateMediaUrl_Fal: '/request-fal',
+               checkRequestStatusUrl_Fal: '/status-fal',
+               getResultUrl_Fal: '/result-fal',
+           });
 
-            If you're using PHP:
+       For PHP:
 
-            const builder = new ContentBox({
-                // ...
-                    
-                textToImageUrl: 'api/texttoimage.php', 
-                upscaleImageUrl: 'api/upscaleimage.php',
-                imageModel: 'flux-schnell',
-                imageAutoUpscale: false,
-            });
+           const builder = new ContentBox({
+               // ...
+               defaultImageGenerationProvider: 'fal',
+               generateMediaUrl_Fal: 'api/request-fal.php',
+               checkRequestStatusUrl_Fal: 'api/status-fal.php',
+               getResultUrl_Fal: 'api/result-fal.php',
+           });
 
 
-    Most examples in the package have this parameter configured, so you can run and test them.
+    Legacy provider - Getimg.ai:
 
-    The JavaScript project example in this package uses Node.js for the API endpoints.
-    Please refer to the Node.js file:
+    1. Get an API key from https://getimg.ai/tools/api and add it to .env:
 
-        server.js
+           GETIMG_API_KEY=YOUR_API_KEY
 
-- To register new plugins, update the following files:
+       (PHP: add $GETIMG_API_KEY = 'YOUR_API_KEY'; to api/config.php)
+
+    2. Set these options:
+
+           const builder = new ContentBox({
+               // ...
+               textToImageUrl: '/texttoimage',
+               upscaleImageUrl: '/upscaleimage',
+               imageModel: 'flux-schnell',
+               imageAutoUpscale: false,
+               // viewFileUrl: '/viewfile',   // if using S3
+           });
+
+       For PHP:
+
+           const builder = new ContentBox({
+               // ...
+               textToImageUrl: 'api/texttoimage.php',
+               upscaleImageUrl: 'api/upscaleimage.php',
+               imageModel: 'flux-schnell',
+               imageAutoUpscale: false,
+           });
+
+    The JavaScript project serves these endpoints from server.js.
+
+
+------------------------------------------------------------------------
+ 6. REGISTERING PLUGINS
+------------------------------------------------------------------------
+
+Pages that display plugin content need the plugins registered. To add
+new plugins, update:
 
     - public/blank-plugins.html
-    - public/preview-with-plugins.html
+    - public/preview.html
 
-    Example with plugin implementation:
+For a full example with plugins in use, see:
 
     - public/example-plugins.html
 
 
-- IMPORTANT: 
+------------------------------------------------------------------------
+ 7. UPGRADING TO A NEW VERSION
+------------------------------------------------------------------------
+
+Updates are backward compatible - your existing content and code keep
+working. You replace the package folders with the new ones:
+
+    public/box/
+    public/contentbox/
+    public/contentbuilder/
+    public/assets/
+    public/runtime/
+    blank.html (or blank-plugins.html)
+    preview.html
 
-    Please add your own security to the API endpoints!
+And if you install from npm, also update the editor script:
 
+    > npm i @innovastudio/contentbox@latest
 
+Full step-by-step instructions, including the Runtime library, are in:
 
-_____________________________________________
-SUPPORT:
+    upgrading-contentbox.md
 
-Email us at: support@innovastudio.com
 
+------------------------------------------------------------------------
+ 8. DOCUMENTATION & SUPPORT
+------------------------------------------------------------------------
 
+    Documentation:  docs/README.md
+                    https://github.com/innovastudio-dev/contentbox/
+    Upgrade guide:  upgrading-contentbox.md
 
+    Questions? Email us at: support@innovastudio.com