@widgetic/creator 0.3.67 → 0.3.68

package/README.md

@@ -1,131 +1,85 @@
 # Widget Creator – Local Development Notes
 
-## VM Preview Configuration
+## Environment variables
 
-The Widget Preview modal proxies through the API Gateway. Configure the front-end by creating or updating `.env.local` with:
-
-```
-VITE_WIDGET_VM_PREVIEW_ORIGIN=http://localhost:3000/v1/agent
-```
-
-After editing the file, restart `pnpm dev` so Vite reloads the environment variables. When a VM session is selected, the modal and “Open in new tab” button will hit:
-
-```
-{VITE_WIDGET_VM_PREVIEW_ORIGIN}/vms/{vmSessionId}/preview
-```
-
-If the variable is missing, the UI shows guidance and logs a single warning in development.
+`.env.example` tracks the full variable inventory — copy it to `.env.local` and
+adjust. It also documents the variables `npm run dev-sv` injects
+(`VITE_APP_VERSION` from the manifest, `VITE_BUILD_SHA` from the current git
+commit) and the optional `VITE_`/`PUBLIC_` variables the app reads, each with
+its fallback.
 
 ## Sibling packages
 
-This app compiles sibling `@widgetic/*` packages from source in dev. That runs
-on the `node_modules/@widgetic/dev-tools` link, which `npm install` prunes as
-an unowned extra — re-run it after every install:
-
-```sh
-npm run i
-npm run ldt      # node_modules/@widgetic/dev-tools -> ../../../dev-tools
-npm run llinks   # show the current @widgetic links
-```
+This app compiles sibling `@widgetic/*` source in dev through the dev-alias
+setup `@widgetic/dev-tools` owns. The alias tables, the `$lib` remap, and
+everything else the mapping needs come from the installed
+`@widgetic/dev-tools` dependency. An ordinary `npm install` is the whole
+setup — there is no linking step.
 
-The why, the silent-degrade failure mode, and the link-doctor check live in
-[the `ldt` workflow](../dev-tools/README.md#the-ldt-workflow-linking-dev-tools-into-an-app).
+The why and the silent-degrade failure mode live in
+[the dev-tools README](../dev-tools/README.md).
 
----
-
-# create-svelte
-
-Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
-
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
-
-```bash
-# create a new project in the current directory
-npm create svelte@latest
-
-# create a new project in my-app
-npm create svelte@latest my-app
-```
+### Chat iteration without publishing
 
-## Developing
+`npm run lps` links `@widgetic/chat` into `node_modules/@widgetic/chat` along
+with design-system, api-sdk and canvas. In `chat/`, `npm run package:watch`
+then emits every source edit into the dist this app resolves through that
+link — a saved change is consumable here within seconds, no manual dist
+copying and no publish. Type-checking resolves through the same files, so
+`npm run check` sees the iteration too. Before merging the chat work, run
+`npm run package && npm publish` in `chat/` and `npm i` here once, so the
+lockfile's `^0.1.11` range admits the real release.
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+---
+## Local development
 
 ```bash
+npm install
 npm run dev
-
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
 ```
 
-## Building
+`npm run dev` frees port 5174 first (`stop-dev`), then starts Vite in
+development mode on that port, injecting `VITE_APP_VERSION` from the
+manifest and `VITE_BUILD_SHA` from the current git commit. The gateway has
+to run for proxied features; `VITE_API_URL` (or its `PUBLIC_API_URL` alias)
+points at it. `npm run dev-sv` starts the same server without the port
+cleanup.
 
-To create a production version of your app:
+### Checks
 
 ```bash
-npm run build
+npm run check              # svelte-kit sync + svelte-check
+npm run lint               # prettier --check + eslint
+npm run format             # prettier --write
+npm test                   # integration (playwright) + unit (vitest)
+npm run test:unit          # vitest only
+npm run test:integration   # playwright only
 ```
 
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
-
+### Building and running the production output
 
-
-
-
-o make it work with both Svelte 4 and Svelte 5, we need to take a more flexible approach. Here's how you can resolve this:
-
-1. First, remove the specific Svelte dependency from your project:
 ```bash
-npm uninstall svelte
-``` 
-
-2. Install svelte-preprocess-react as a dev dependency:
-```bash
-npm install --save-dev svelte-preprocess-react
-```
-
-3. In your package.json, add a peer dependency for Svelte that allows both version 4 and 5:
-```json
-"svelte": "^4.0.0 || ^5.0.0-next.0"
+npm run build              # vite build (NODE_ENV=production) + svelte-package
+npm run preview            # vite preview of the built app
 ```
 
-4. Update your svelte.config.js (or create one if it doesn't exist) to use svelte-preprocess-react:
-```js
-import preprocessReact from 'svelte-preprocess-react/preprocessReact';
+The build emits the Node server into `build/` and the library surface into
+`dist/`. Run the server locally with:
 
-export default {
-	preprocess: [preprocessReact()]
-};
-``` 
-
-5. In your project's root, create a .npmrc file (if it doesn't exist) and add:
 ```bash
-legacy-peer-deps=true
+npm start                  # node build/index.js (adapter-node output)
 ```
-This allows npm to install packages with peer dependencies that don't strictly match.
 
-6. Clear your npm cache:
-```bash
-npm cache clean --force
-```
+The Render deploy wraps the same build in `npm run render-build`
+(`render-build.sh`).
 
-7. Remove the node_modules folder and package-lock.json:
-```bash
-rm -rf node_modules package-lock.json
-```
+### When the dev server misbehaves
 
-8. Reinstall dependencies:
 ```bash
-npm install
+npm run clean-svelte-cache   # rm -rf .svelte-kit && svelte-kit sync
+npm run clean-vite-cache     # rm -rf node_modules/.vite
+npm run clean-npm-cache      # npm cache clean --force
 ```
 
-These steps should resolve the dependency conflicts and allow your project to work with both Svelte 4 and Svelte 5. The key points are:
-- Using peer dependencies to allow flexibility in the Svelte version.
-- Using svelte-preprocess-react as a dev dependency to handle React preprocessing.
-- Allowing legacy peer dependencies to resolve version conflicts.
-- Remember to adjust your code to be compatible with both Svelte 4 and Svelte 5 syntax where necessary. For example, use conditional imports or runtime checks to handle differences between versions.
-- If you still encounter issues, you might need to review other dependencies in your project that might be causing conflicts with Svelte versions.
+`npm run find-sveltekit-running` shows what holds port 5173;
+`npm run stop-dev` frees 5174.