Bundle Development Host

The application is the development host. It watches the selected project, builds immutable revisions under that project’s .kawaikara/development/ directory, validates the normal Bundle and Provider manifests, and activates the revision through the same BundleManager, PluginHost, SiteManager, permission, Session, and PiP pipeline used by installed Bundles.

Project configuration

Place kawaikara.dev.json at the project root:

{
  "schemaVersion": 1,
  "sourceDirectory": "src",
  "entryPoints": [
    "Providers/Example/Provider.ts",
    "Providers/Example/Plugins/Helper/Plugin.ts"
  ],
  "watch": [
    "src",
    "kawaikara.dev.json",
    "package.json",
    "tsconfig.json"
  ]
}

Entry points are relative to sourceDirectory. Watch paths are relative to the project root and must already exist. Every path is resolved to a real path and must remain inside the selected project.

The generated revision directory can be selected in package.json:

{
  "kawaikara": {
    "development": {
      "outputDirectory": ".kawaikara/development"
    }
  }
}

The path must be relative to the project and cannot overlap the source or a watched directory. The default is .kawaikara/development. Detach and reattach the project after changing this path so an active revision is never removed or mixed with the next output location. Add a custom output directory to the project’s ignore file when it is not already covered.

Kawaikara copies non-TypeScript resources from sourceDirectory, bundles each entry as CommonJS with source maps, and leaves @kawaikara/site-api external. The normal runtime bridge then supplies the exact Site API instance owned by the application.

Hot reload lifecycle

1. Debounce a source change.
2. Build a new immutable revision.
3. Validate all manifests, permissions, paths, and compiled entries.
4. Construct the next Bundle definition before touching the running Bundle.
5. Unload an active Provider owned by that Bundle.
6. Replace registrations and restore the active Provider when it still exists.
7. Roll back to the previous definition if registration or Provider loading fails.
8. Evict CommonJS cache entries only below the retired revision root.

Browser Sessions and cookies are not cleared by hot reload. Detaching a project removes its runtime definitions and that project’s .kawaikara/development/ directory, but never deletes project source files or other .kawaikara data. Only the small attached-project registry remains in Kawaikara app data.

Multiple projects may be attached and watched at the same time. Bundle, Provider, Plugin, browser-profile, and shortcut identifiers must remain unique across the running application. A conflicting project fails activation without replacing the Bundle that already owns the identifier.

JSON Schema and editor completion

@kawaikara/site-api publishes JSON Schemas for Bundle, Provider, and Plugin manifests, kawaikara.dev.json, and the Kawaikara section of package.json. The Bundle template synchronizes the installed package schemas into the ignored .kawaikara/schemas/ directory during postinstall and maps them through .vscode/settings.json. Updating @kawaikara/site-api and running pnpm install therefore updates completion without modifying tracked project files. A checked-in fallback supports older API packages that do not yet ship schemas. Standard package.json completion stays available alongside the additional kawaikara property.

Editors other than VS Code can associate the files with the matching schemas from @kawaikara/site-api/schemas using their normal JSON Schema settings.

Schema compatibility follows two separate versions:

• apiVersion selects the runtime Site API contract.
• schemaVersion selects the JSON manifest shape.

Backward-compatible additions ship with a normal Site API release. A breaking JSON shape must increment schemaVersion; the Site API package must retain the older versioned schema so existing projects keep their previous validation.

VS Code debugging

Enable the Main process debugger in the same preference page. Kawaikara opens a Node Inspector endpoint on 127.0.0.1 only; the default port is 9230. Preferences can copy a complete VS Code attach configuration.

{
  "name": "Attach to Kawaikara Bundle",
  "type": "node",
  "request": "attach",
  "address": "127.0.0.1",
  "port": 9230,
  "sourceMaps": true,
  "restart": true
}

Attach before rebuilding when a breakpoint must catch module initialization or a Provider constructor. Hot reload evaluates a new script while the Inspector connection remains active, allowing source-mapped breakpoints to bind again.

Page-world injection executes in a site renderer rather than Main. Use the site DevTools for that code; Main Inspector breakpoints apply to Provider, Plugin, and Site API calls that execute in the Electron Main process.

Trust boundary

A development Bundle is trusted local Main-process code. Development mode is disabled by default, Inspector listens only on loopback, and only explicitly selected projects are persisted. Attach projects and dependencies only when their code is trusted.