@fluid-app/fluid-cli-widget 0.1.3 → 0.1.5

package/templates/default/AGENTS.md

@@ -2,9 +2,184 @@
 
 Guidance for AI coding tools working in this standalone Fluid widget project.
 
-- This project contains a widget package only; do not scaffold or create droplets here.
-- Author widgets with `defineWidget()` and `defineWidgetPackage()` from `@fluid-app/portal-sdk`.
+This repository is a generated Fluid widget package. Treat these instructions as the source of truth for code generated here. Do not assume the parent Fluid monorepo is present.
+
+## Project boundary
+
+- This project contains a widget package only. Do not scaffold droplets, portal apps, Next.js apps, Rails code, API servers, or monorepo packages here.
+- Use React, TypeScript, Vite, and the Fluid widget CLI scripts already in `package.json`.
 - Keep widget source under `src/widgets/` and package metadata in `manifest.ts`.
-- Run `pnpm validate` before considering changes complete.
-- Use React + TypeScript + Vite patterns; do not add Next.js app structure.
-- Keep runtime styles in `styles.css` and import them from a module loaded by the widget builder (for example `manifest.ts` or the widget component) so generated CSS artifacts are discovered automatically.
+- Keep runtime registration in `src/index.ts`. Do not rewrite the global registration protocol unless the Fluid widget CLI changes.
+- Keep package ownership in `fluid.widget.config.ts`. For droplet-owned widgets, link or set the droplet with `pnpm run widget:link` or `fluid widget link`; do not hard-code a droplet into component source.
+- Runtime CSS belongs in `styles.css` or files imported by modules loaded by the widget builder. Import CSS from `manifest.ts` or the widget component so build artifacts are discovered.
+
+## Manifest authoring
+
+Use `defineWidget()` and `defineWidgetPackage()` from `@fluid-app/portal-sdk`.
+
+### `defineWidget()` checklist
+
+Each widget should define:
+
+- `name`: stable, URL-safe widget name. Use letters, numbers, underscore, hyphen, or tilde. Changing it changes the generated widget type.
+- `component`: React component that renders the widget.
+- `displayName`, `description`, `icon`, and `category`: palette metadata for the builder.
+- `defaultProps`: JSON-serializable default props. Do not use functions, Dates, undefined values, class instances, NaN, or Infinity.
+- `propertySchema`: JSON-serializable editable fields for the builder property panel.
+- `container`: usually `block` or `card`; use `inline` only for inline content and `fullscreen` only for true full-screen experiences.
+- `resizable`: omit or set false for fixed widgets; otherwise use `true`, `horizontal`, `vertical`, `both`, or an object with horizontal/vertical booleans and optional min sizes.
+
+### `defineWidgetPackage()` checklist
+
+The generated package is droplet-owned:
+
+- `scope` is the namespace passed at project creation.
+- `packageType` must stay `droplet`.
+- `version` must be SemVer without build metadata, such as `1.2.3` or `1.2.3-beta.1`.
+- `remoteEntryUrl` should stay `widget.js` for the standalone publish flow.
+- `widgets` must contain at least one `defineWidget()` result.
+- Do not manually set `packageStableId` for the default droplet template. The CLI injects the linked droplet as the stable package key during validation, build, and publish.
+
+## Property schema reference
+
+A property schema describes the builder editing UI. Use this shape:
+
+```ts
+propertySchema: {
+  tabsConfig: [{ id: "content", label: "Content" }],
+  dataSourceTargetProps: ["title", "items"],
+  fields: [
+    {
+      key: "title",
+      label: "Title",
+      type: "text",
+      defaultValue: "Featured items",
+      tab: "content",
+      group: "Copy",
+    },
+  ],
+}
+```
+
+Base field keys:
+
+- `key`: prop key written into widget props. For visual-only fields such as section headers, use a unique non-prop key.
+- `label`: human-readable property label.
+- `type`: one of the supported field types below.
+- `description`: optional helper text.
+- `defaultValue`: optional JSON-serializable value matching the prop.
+- `tab`: optional tab id from `tabsConfig`.
+- `group`: optional group label inside a tab.
+- `advanced`: true for theme override controls; advanced fields render in the Custom styling group.
+- `requiresKeyValue`: conditionally show the field when another prop has a value. Arrays are AND logic.
+
+Supported field types:
+
+- `text`: single-line string. Optional `placeholder`, `maxLength`, `tokenSuggestions`.
+- `textarea`: multi-line string. Optional `placeholder`, `rows`, `maxLength`.
+- `number`: numeric input. Optional `min`, `max`, `step`.
+- `boolean`: toggle.
+- `select`: dropdown. Requires `options` with `label` and `value` entries.
+- `color`: basic color value.
+- `range`: slider. Requires `min` and `max`; optional `step`.
+- `dataSource`: data-source selector/configuration entry point.
+- `resource`: single shareable/resource selector. Optional `allowedTypes`.
+- `image`: media picker. Optional `accept` as `image`, `video`, or `any`.
+- `alignment`: alignment picker. Requires `options.verticalEnabled` and `options.horizontalEnabled`.
+- `slider`: numeric slider with optional `unit` suffix plus `min`, `max`, and `step`.
+- `colorPicker`: color picker with optional `swatches`.
+- `sectionHeader`: visual grouping header with optional `subtitle`.
+- `separator`: visual separator.
+- `buttonGroup`: segmented control. Requires `options`; each option has `value` plus optional `label`, `ariaLabel`, and icon.
+- `colorSelect`: semantic theme color selector. Optional `excludeColors`.
+- `sectionLayoutSelect`: visual layout selector.
+- `background`: combined resource/color background control.
+- `contentPosition`: 3-by-3 content position picker.
+- `textSizeSelect`: theme text size selector.
+- `cssUnit`: number plus unit. Optional `allowedUnits`, `defaultUnit`, and min/max/step maps per unit.
+- `fontPicker`: Google font picker with optional `placeholder`.
+- `stringArray`: editable list of strings with optional `placeholder`.
+- `borderRadius`: composite radius editor. Requires `keys.topLeft`, `keys.topRight`, `keys.bottomLeft`, and `keys.bottomRight` mapping to real prop keys.
+- `screenPicker`: portal screen picker. Optional `includeSystemItems`.
+
+Data-source-ready props:
+
+- Add bindable prop keys to `dataSourceTargetProps`.
+- Keep those prop types serializable and tolerant of missing, empty, or partially populated data.
+- For arrays, render empty states and validate each item before reading nested properties.
+- Keep manual defaults in `defaultProps`; data sources should override props without requiring component rewrites.
+- If selected data needs per-item settings, add `itemConfigSchema` with its own `fields` array.
+
+## Component quality bar
+
+- Components must be deterministic, portable, and host-safe. Avoid direct assumptions about the embedding portal, route, global CSS reset, or parent DOM.
+- Props are untrusted. Provide defaults, guard array access, and handle nullish values.
+- Use stable keys for lists. Do not use array indexes when items have stable ids.
+- Avoid side effects during render. Use effects only for host-safe subscriptions and clean them up.
+- Do not fetch data directly unless the widget explicitly owns that integration. Prefer props and data-source-ready schemas.
+- Keep bundle weight small. Avoid large UI kits or date/chart libraries unless the widget truly needs them.
+- Do not store secrets, API tokens, or tenant-specific credentials in source, props, or defaultProps.
+
+## Accessibility requirements
+
+- Use semantic HTML first: sections, headings, buttons, lists, forms, and labels.
+- Every interactive control must be keyboard reachable and have a visible focus state.
+- Icon-only buttons need `aria-label`.
+- Images need meaningful alt text, or empty alt text when decorative.
+- Preserve heading order inside the widget; do not choose headings based only on size.
+- Announce dynamic changes when necessary with appropriate ARIA live regions.
+- Meet contrast expectations by using theme foreground/background token pairs.
+- Respect reduced motion for animation-heavy widgets.
+
+## Theme and styling guidance
+
+Fluid hosts provide semantic CSS variables. Prefer those over hard-coded colors:
+
+- Surfaces: `--background`, `--card`, `--popover`.
+- Text on surfaces: `--foreground`, `--card-foreground`, `--popover-foreground`.
+- Brand/action: `--primary`, `--primary-foreground`.
+- Supporting UI: `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`.
+- Status and chrome: `--destructive`, `--destructive-foreground`, `--border`, `--input`, `--ring`.
+- Charts: `--chart-1` through `--chart-5`.
+- Radius: `--radius`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`.
+- Theme engine aliases may also provide `--font-header`, `--font-body`, `--font-size-extra-small`, `--font-size-small`, `--font-size-regular`, `--font-size-large`, `--font-size-extra-large`, and `--font-size-giant`.
+
+Tailwind equivalents, when Tailwind is available in a host or preview, are the semantic utilities: `bg-background`, `text-foreground`, `bg-card`, `text-card-foreground`, `bg-primary`, `text-primary-foreground`, `border-border`, `ring-ring`, `rounded-lg`, and text sizes such as `text-sm` or `text-xl`. In this standalone template, plain CSS is the safest runtime default.
+
+Light/dark behavior:
+
+- The portal switches theme values with `data-theme-mode="dark"` and may also honor system dark mode when configured.
+- Do not write separate hard-coded dark palettes unless absolutely necessary. Use semantic variables so the host theme controls both modes.
+- If you need mode-specific refinements, scope them to `[data-theme-mode="dark"]` and keep them token-based.
+- Avoid styling that only works on white backgrounds. Test in the local builder preview dark toggle and with high-contrast colors.
+
+Runtime CSS rules:
+
+- Put runtime selectors in `styles.css` or imported CSS modules.
+- Keep selectors prefixed with the widget name to avoid leaking styles into the host.
+- Do not rely on global body styles for runtime appearance; body styles are only for local preview.
+- Ensure CSS is imported by `manifest.ts` or another module included in the widget build, otherwise CSS artifacts may not be published.
+
+## Validation workflow
+
+Before considering changes complete, run:
+
+```bash
+pnpm typecheck
+pnpm validate
+pnpm build
+```
+
+Use `pnpm dev` for local preview and `pnpm run widget:publish -- --dry-run` when checking publish readiness without uploading.
+
+Common failures and fixes:
+
+- Missing droplet UUID: run `pnpm run widget:link` or pass `--droplet` to validate/build/publish commands.
+- No source package found: ensure `fluid.widget.config.ts` exports `widgetPackage` or `widgetPackages` from `manifest.ts`.
+- Invalid package type: keep `packageType: "droplet"` in `defineWidgetPackage()`.
+- Invalid widget name or package key: use URL-safe names only.
+- Invalid version: use SemVer without build metadata.
+- Non-serializable metadata: remove functions, undefined values, Dates, NaN, Infinity, Maps, Sets, and class instances from `propertySchema` and `defaultProps`.
+- CSS URL mismatch: import runtime CSS into the bundle or remove manual `cssUrls` entries.
+- Build succeeds but styles are missing: confirm the CSS import is reachable from `manifest.ts` or the widget component.
+- Preview works but published widget fails: check that browser-only APIs are guarded and no local-only URLs or environment variables are required at runtime.

package/templates/default/README.md.template

@@ -0,0 +1,271 @@
+# {{projectName}}
+
+Standalone Fluid widget project generated by `@fluid-app/fluid-cli-widget`.
+
+This project builds and publishes a widget package only. It does **not** scaffold droplets, a full portal application, or backend services.
+
+## Scripts
+
+```bash
+pnpm dev                              # Run the local Vite/builder preview
+pnpm typecheck                        # Run TypeScript checking
+pnpm validate                         # Validate package metadata with the Fluid widget CLI
+pnpm build                            # Validate and build runtime artifacts
+pnpm run widget:link                  # Link this project to an existing Fluid droplet
+pnpm run widget:publish               # Publish to the linked droplet
+pnpm run widget:publish -- --dry-run  # Build upload payload without uploading
+```
+
+## Project structure
+
+```text
+.
+├── AGENTS.md                         # Portable AI authoring guidance
+├── CLAUDE.md                         # Claude-compatible AI authoring guidance
+├── .agents/skills/                   # Agent skill docs for this project
+├── .claude/skills/                   # Claude skill docs for this project
+├── fluid.widget.config.ts            # Widget CLI config and manifest exports
+├── manifest.ts                       # defineWidget/defineWidgetPackage metadata + runtime CSS import
+├── styles.css                        # Runtime + preview styles
+├── src/index.ts                      # Runtime registration entry
+├── src/widget-preview.tsx            # Local preview entry
+└── src/widgets/review-carousel/ReviewCarousel.tsx
+```
+
+## Package boundary
+
+Stay inside the standalone widget package:
+
+- Put reusable widget components under `src/widgets/`.
+- Put package and palette metadata in `manifest.ts`.
+- Keep runtime registration in `src/index.ts`.
+- Keep runtime styles in `styles.css` or CSS files imported by widget modules.
+- Do not add Next.js app folders, Rails code, API servers, portal app shells, or droplet scaffolding.
+
+Droplet ownership is managed by the Fluid widget CLI through `fluid.widget.config.ts`. Link the project with `pnpm run widget:link` or pass a droplet option to CLI commands when needed.
+
+## Authoring widgets
+
+Widgets are authored with `defineWidget()` and grouped with `defineWidgetPackage()` from `@fluid-app/portal-sdk`.
+
+`defineWidget()` describes one widget:
+
+- `name`: stable URL-safe widget name. Changing it changes the generated widget type.
+- `component`: React component rendered by the host.
+- `displayName`, `description`, `icon`, `category`: builder palette metadata.
+- `defaultProps`: JSON-serializable defaults for new widget instances.
+- `propertySchema`: builder property panel fields.
+- `container`: `block`, `card`, `inline`, or `fullscreen`.
+- `resizable`: false/omitted, true, `horizontal`, `vertical`, `both`, or an object with horizontal/vertical flags and optional minimum sizes.
+
+`defineWidgetPackage()` describes the package:
+
+- Keep `packageType` set to `droplet` for this template.
+- Keep `remoteEntryUrl` as `widget.js` for the default publish flow.
+- Keep `widgets` as the array of widgets exported by this package.
+- Use a SemVer `version` without build metadata.
+- Do not manually set `packageStableId` in this generated droplet template; the CLI injects the linked droplet key during validation, build, and publish.
+
+## Manifest structure
+
+`manifest.ts` should remain the single source of package metadata:
+
+```ts
+import { defineWidget, defineWidgetPackage } from "@fluid-app/portal-sdk";
+import "./styles.css";
+import { ExampleWidget } from "./src/widgets/example/ExampleWidget";
+
+export const exampleWidget = defineWidget({
+  name: "ExampleWidget",
+  component: ExampleWidget,
+  displayName: "Example Widget",
+  description: "A focused reusable Fluid widget.",
+  icon: "box",
+  category: "components",
+  container: "card",
+  defaultProps: {
+    title: "Featured content",
+  },
+  propertySchema: {
+    tabsConfig: [{ id: "content", label: "Content" }],
+    dataSourceTargetProps: ["title"],
+    fields: [
+      {
+        key: "title",
+        label: "Title",
+        type: "text",
+        defaultValue: "Featured content",
+        tab: "content",
+        group: "Copy",
+      },
+    ],
+  },
+});
+
+export const widgetPackage = defineWidgetPackage({
+  scope: "droplet",
+  version: "0.1.0",
+  packageType: "droplet",
+  remoteEntryUrl: "widget.js",
+  widgets: [exampleWidget],
+});
+
+export const widgetPackages = [widgetPackage] as const;
+export default widgetPackage;
+```
+
+## Property schema reference
+
+Property schemas define editable builder controls. They must be JSON-serializable.
+
+Top-level schema keys:
+
+- `tabsConfig`: optional array of tab objects with `id` and `label`.
+- `fields`: array of controls shown in the builder property panel.
+- `dataSourceTargetProps`: prop keys that can be populated from configured data sources.
+- `itemConfigSchema`: optional per-item configuration schema for custom data-source selections.
+- `validate`: optional custom validator in in-app manifests; avoid it for published standalone metadata because package metadata must be serializable.
+
+Base field keys:
+
+| Key | Purpose |
+| --- | --- |
+| `key` | Widget prop key written by the field. Use a unique non-prop key for visual-only controls. |
+| `label` | Builder label. |
+| `type` | Supported field type listed below. |
+| `description` | Optional helper text. |
+| `defaultValue` | Optional JSON-serializable default. |
+| `tab` | Optional tab id matching `tabsConfig`. |
+| `group` | Optional group label inside a tab. |
+| `advanced` | Marks theme overrides or low-frequency settings; advanced fields render in Custom styling. |
+| `requiresKeyValue` | Optional conditional display rule. An array means all conditions must match. |
+
+Supported field types:
+
+| Type | Use | Extra keys |
+| --- | --- | --- |
+| `text` | Single-line string | `placeholder`, `maxLength`, `tokenSuggestions` |
+| `textarea` | Multi-line string | `placeholder`, `rows`, `maxLength` |
+| `number` | Number input | `min`, `max`, `step` |
+| `boolean` | Toggle | None |
+| `select` | Dropdown | `options` array with `label` and `value` |
+| `color` | Basic color value | None |
+| `range` | Slider | Required `min`, `max`; optional `step` |
+| `dataSource` | Data-source selector/configuration | None |
+| `resource` | Single shareable/resource picker | `allowedTypes` |
+| `image` | Media picker | `accept` as `image`, `video`, or `any` |
+| `alignment` | Alignment picker | `options.verticalEnabled`, `options.horizontalEnabled` |
+| `slider` | Numeric slider | `min`, `max`, `step`, `unit` |
+| `colorPicker` | Color picker | `swatches` |
+| `sectionHeader` | Visual section heading | `subtitle` |
+| `separator` | Visual divider | None |
+| `buttonGroup` | Segmented choice | `options` with `value`, optional `label`, `ariaLabel`, `icon` |
+| `colorSelect` | Semantic theme color picker | `excludeColors` |
+| `sectionLayoutSelect` | Visual section layout picker | None |
+| `background` | Combined background resource/color control | Resource/color field keys as needed |
+| `contentPosition` | 3-by-3 content position picker | None |
+| `textSizeSelect` | Theme text-size picker | None |
+| `cssUnit` | Number with unit selector | `allowedUnits`, `defaultUnit`, `minByUnit`, `maxByUnit`, `stepByUnit` |
+| `fontPicker` | Google font picker | `placeholder` |
+| `stringArray` | Editable list of strings | `placeholder` |
+| `borderRadius` | Composite four-corner radius editor | `keys.topLeft`, `keys.topRight`, `keys.bottomLeft`, `keys.bottomRight` |
+| `screenPicker` | Portal screen picker | `includeSystemItems` |
+
+### Data-source-ready props
+
+For props that may later be connected to data sources:
+
+- Add the prop key to `dataSourceTargetProps`.
+- Keep the component tolerant of missing, empty, or partially populated values.
+- Render useful empty states for empty arrays and failed mapping.
+- Keep prop values JSON-serializable.
+- Avoid fetching inside the component when a prop or data source can provide the data.
+- Use `itemConfigSchema` when each selected item needs widget-specific settings.
+
+## Component quality bar
+
+- Use TypeScript interfaces for public props.
+- Provide defaults for optional props.
+- Treat incoming props as untrusted and validate before reading nested values.
+- Keep render logic deterministic and side-effect free.
+- Clean up effects and subscriptions.
+- Keep bundles small; avoid heavy libraries unless the widget requires them.
+- Avoid secrets, tenant credentials, local URLs, and environment-only assumptions.
+- Prefer semantic HTML over div-only structures.
+
+## Accessibility
+
+- Use headings, sections, lists, buttons, labels, and form elements semantically.
+- Make every interactive element keyboard reachable.
+- Provide visible focus states.
+- Add `aria-label` to icon-only controls.
+- Add alt text to meaningful images and empty alt text to decorative images.
+- Preserve logical heading order inside the widget.
+- Use ARIA live regions for important dynamic updates.
+- Respect reduced-motion preferences for animation-heavy widgets.
+- Use semantic foreground/background token pairs for contrast.
+
+## Runtime CSS and theme tokens
+
+Fluid hosts provide semantic CSS variables. Prefer token-based CSS instead of hard-coded palettes.
+
+Common CSS variables:
+
+- Surfaces: `--background`, `--card`, `--popover`.
+- Text: `--foreground`, `--card-foreground`, `--popover-foreground`.
+- Brand/actions: `--primary`, `--primary-foreground`.
+- Supporting UI: `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`.
+- Status/chrome: `--destructive`, `--destructive-foreground`, `--border`, `--input`, `--ring`.
+- Charts: `--chart-1`, `--chart-2`, `--chart-3`, `--chart-4`, `--chart-5`.
+- Radius: `--radius`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`.
+- Theme-engine aliases may include `--font-header`, `--font-body`, `--font-size-extra-small`, `--font-size-small`, `--font-size-regular`, `--font-size-large`, `--font-size-extra-large`, and `--font-size-giant`.
+
+Tailwind equivalents, when Tailwind is available, are semantic utilities such as `bg-background`, `text-foreground`, `bg-card`, `text-card-foreground`, `bg-primary`, `text-primary-foreground`, `border-border`, `ring-ring`, `rounded-lg`, `text-sm`, and `text-xl`. This standalone template uses plain CSS for runtime portability.
+
+Light/dark behavior:
+
+- Fluid themes update variables for light and dark mode.
+- Explicit dark mode is represented by `data-theme-mode="dark"` on a host element.
+- Some hosts also use system dark mode when no explicit mode is selected.
+- Prefer semantic variables so both modes work automatically.
+- If mode-specific styling is unavoidable, scope it with `[data-theme-mode="dark"]` and keep values token-based.
+
+Runtime CSS rules:
+
+- Import runtime CSS from `manifest.ts` or a widget module included in the build.
+- Prefix selectors with the widget name to prevent host leakage.
+- Do not rely on `body` styles for published runtime rendering; body styles are preview-only.
+- If published styles are missing, check that the CSS import is reachable from the built entry.
+
+## Validation, build, and publish preflight
+
+Before shipping changes, run:
+
+```bash
+pnpm typecheck
+pnpm validate
+pnpm build
+pnpm run widget:publish -- --dry-run
+```
+
+Publish only after the dry run succeeds:
+
+```bash
+pnpm run widget:publish
+```
+
+Build output is written under `.fluid/widget-dist/`. The runtime entry registers the package with `window.FluidWidgets` when loaded by a Fluid portal host.
+
+## Common failures
+
+| Failure | Fix |
+| --- | --- |
+| Missing droplet UUID | Run `pnpm run widget:link` or pass a droplet option to validate/build/publish. |
+| No source package found | Ensure `fluid.widget.config.ts` exports `widgetPackage` or `widgetPackages` from `manifest.ts`. |
+| Invalid package type | Keep `packageType: "droplet"`. |
+| Invalid package key or widget name | Use URL-safe letters, numbers, dots for package keys, and underscore/hyphen/tilde where allowed. |
+| Invalid version | Use SemVer without build metadata. |
+| Non-serializable metadata | Remove functions, undefined values, Dates, NaN, Infinity, Maps, Sets, and class instances from `propertySchema` and `defaultProps`. |
+| Relative CSS URL rejected | Import CSS into the bundle or remove manual `cssUrls` entries. |
+| Styles present in preview but absent after publish | Confirm `styles.css` is imported by `manifest.ts` or a widget module loaded by the builder. |
+| Published widget fails but preview works | Guard browser-only APIs, remove local-only URLs, and avoid environment variables required at runtime. |

package/templates/default/package.json.template

@@ -32,6 +32,7 @@
     "typescript": "^5.6.0",
     "vite": "^6.4.1",
     "@fluid-app/fluid-cli-widget": "{{widgetCliVersion}}",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3"
   },

package/templates/default/vite.config.ts

@@ -1,9 +1,19 @@
 import { defineConfig } from "vite";
 import type { Plugin, ViteDevServer } from "vite";
 import react from "@vitejs/plugin-react";
+import type { IncomingMessage, ServerResponse } from "node:http";
 
 export default defineConfig({
   plugins: [react(), fluidWidgetDevRoutes()],
+  resolve: {
+    conditions: ["fluid-widget-authoring"],
+  },
+  ssr: {
+    noExternal: ["@fluid-app/portal-sdk"],
+    resolve: {
+      conditions: ["fluid-widget-authoring"],
+    },
+  },
 });
 
 function fluidWidgetDevRoutes(): Plugin {
@@ -11,49 +21,53 @@ function fluidWidgetDevRoutes(): Plugin {
     name: "fluid-widget-dev-routes",
     apply: "serve",
     configureServer(server: ViteDevServer) {
-      server.middlewares.use(
-        async (req: DevRequest, res: DevResponse, next: () => void) => {
-          const pathname = (req.url ?? "").split("?")[0] ?? "";
-
-          if (
-            pathname === "/builder-preview" ||
-            pathname === "/builder-preview/"
-          ) {
-            await sendTransformedHtml(
-              server,
-              res,
-              "/builder-preview",
-              getBuilderPreviewHtml(),
-            );
-            return;
-          }
-
-          if (pathname === "/__preview__" || pathname === "/__preview__/") {
-            await sendTransformedHtml(
-              server,
-              res,
-              "/__preview__",
-              getPreviewHtml(),
-            );
-            return;
-          }
-
-          if (
-            pathname === "/__runtime-entry__" ||
-            pathname === "/__runtime-entry__/"
-          ) {
-            sendJavaScript(req, res, 'void import("/src/index.ts");\n');
-            return;
-          }
-
-          if (pathname === "/__manifests__" || pathname === "/__manifests__/") {
-            await sendManifests(server, req, res);
-            return;
-          }
-
-          next();
-        },
-      );
+      const devRoutesHandler = async (
+        req: DevRequest,
+        res: DevResponse,
+        next: (err?: unknown) => void,
+      ): Promise<void> => {
+        const pathname = (req.url ?? "").split("?")[0] ?? "";
+
+        if (
+          pathname === "/builder-preview" ||
+          pathname === "/builder-preview/"
+        ) {
+          await sendTransformedHtml(
+            server,
+            res,
+            "/builder-preview",
+            getBuilderPreviewHtml(),
+          );
+          return;
+        }
+
+        if (pathname === "/__preview__" || pathname === "/__preview__/") {
+          await sendTransformedHtml(
+            server,
+            res,
+            "/__preview__",
+            getPreviewHtml(),
+          );
+          return;
+        }
+
+        if (
+          pathname === "/__runtime-entry__" ||
+          pathname === "/__runtime-entry__/"
+        ) {
+          sendJavaScript(req, res, 'void import("/src/index.ts");\n');
+          return;
+        }
+
+        if (pathname === "/__manifests__" || pathname === "/__manifests__/") {
+          await sendManifests(server, req, res);
+          return;
+        }
+
+        next();
+      };
+
+      server.middlewares.use(devRoutesHandler);
     },
   };
 }
@@ -164,16 +178,8 @@ function getPreviewHtml(): string {
 </html>`;
 }
 
-interface DevRequest {
-  readonly method?: string;
-  readonly url?: string;
-}
-
-interface DevResponse {
-  statusCode: number;
-  setHeader(name: string, value: string): void;
-  end(body?: string): void;
-}
+type DevRequest = IncomingMessage;
+type DevResponse = ServerResponse;
 
 interface SourceWidgetPackage {
   readonly packageId: string;

package/templates/default/README.md

@@ -1,38 +0,0 @@
-# {{projectName}}
-
-Standalone Fluid widget project generated by `@fluid-app/fluid-cli-widget`.
-
-This project builds a widget package only. It does **not** scaffold droplets or a full portal application.
-
-## Scripts
-
-```bash
-pnpm dev                 # Run the local Vite preview
-pnpm validate            # Validate the widget package with the Fluid widget CLI
-pnpm build               # Build the widget runtime bundle with the Fluid widget CLI
-pnpm run widget:publish  # Publish with the Fluid widget CLI
-```
-
-## Project structure
-
-```text
-.
-├── fluid.widget.config.ts       # Widget package config export
-├── manifest.ts                  # defineWidget/defineWidgetPackage metadata + runtime CSS import
-├── styles.css                   # Runtime + preview styles
-├── src/index.ts                 # Runtime registration entry
-├── src/widget-preview.tsx       # Local preview entry
-└── src/widgets/review-carousel/ReviewCarousel.tsx
-```
-
-## Authoring widgets
-
-Widgets are authored with `defineWidget()` and grouped with `defineWidgetPackage()` from `@fluid-app/portal-sdk`.
-
-Edit `manifest.ts` to update package metadata such as `version` and to add widgets. Droplet package identity is managed by the Fluid widget CLI from `fluid.widget.config.ts` and the linked droplet.
-
-Add new widgets under `src/widgets/`, import them in `manifest.ts`, and add them to the `widgets` array. Keep runtime CSS imported by `manifest.ts` or another module loaded by the widget builder; the build discovers emitted CSS artifacts automatically.
-
-## Build output
-
-`pnpm build` validates the package and writes runtime artifacts under `.fluid/widget-dist/`. The runtime entry registers the package with `window.FluidWidgets` when loaded by a Fluid portal host.