arcane-os 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.26.0
+
+- Add explicit installed-package browser runtime routes. Source development,
+  managed import maps, application test-map resolution, and PWA resource
+  selection can use the npm dependency directly without a generated workspace
+  runtime or lock. Keep existing browser URLs, aliases, and materialized layouts.
+- Let a shared package route select its complete source directory with
+  `include: ["."]`. Portable app output includes the selected runtime,
+  dependencies, assets, and notices without requiring the SDK at deployment.
+- Expose lowercase public module subpaths for shared AI preferences, provider
+  state, model definitions, conversation helpers, application data, document
+  libraries, and local AI readiness. Browser maps and Node package resolution
+  select the same canonical implementations; browser runtime requirements remain.
+- Share the existing portable Mail aggregation with browser import maps while
+  preserving the `arcane-os/mail` API and Node mail CLI used by server consumers.
+
 ## 0.25.0
 
 - Automatically skip configured mail subscription verification when the actual

package/README.md

@@ -19,10 +19,19 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.25.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.26.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
+External browser apps can use the installed npm package directly, without a
+generated workspace `arcane/` directory or `arcane.lock.json`. Select the
+[four installed-package routes](docs/reference/protocols.md#installed-package-browser-routes)
+in `arcane-packager.json`: development, managed import maps, and PWA resources
+read the installed SDK while keeping `/arcane/...` browser URLs. Portable app
+packages still contain their selected runtime. Existing materialized workspaces
+and the scaffold's current layout remain supported. Node services continue to
+use the installed CLI or public imports such as `arcane-os/mail`.
+
 The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433
 by default. Configure its host, port, origin list, certificate paths, and other
 mail settings in `arcane.config.json.mail`; keep provider keys in the ignored
@@ -62,7 +71,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.12.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.26.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

package/docs/architecture.md

@@ -84,13 +84,22 @@ runtime materialization, serving, and coordination with other writers. This
 path requires no application descriptor or `apps/<id>/` layout and leaves the
 app-scoped toolchain operation unchanged.
 
-An external workspace maps the exact runtime shipped by its locked `arcane-os`
-dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
+An external workspace can select `installed-v1` routes directly from its
+`node_modules/arcane-os` installation, without a workspace `arcane/` tree or
+`arcane.lock.json`. The SDK reads the installed package version and maps its
+runtime, browser runtime, runtime dependency, and licenses to the established
+browser destinations. Existing `physical-v1` workspaces and the explicit
+materializer remain supported; scaffolding retains its existing physical
+layout. See [installed-package routes](reference/protocols.md#installed-package-browser-routes)
+for the configuration and npm-alias form.
+
+An Arcane OS checkout is an integrated SDK consumer, not the owner
 of portable runtime source. For live shared development, the explicit
 development-only SDK source mount maps the canonical SDK runtime and dependency
-paths into that consumer. Without the mount, the workspace uses its locked SDK
-projection. The development server and packager consume the same route
-destinations in both cases, so app imports do not change. Integrated
+paths into that consumer. Without the mount, integrated workspaces retain their
+physical projection; external workspaces select either layout above. The development server,
+import-map generator, packager, and PWA inventory consume the same route
+destinations, so app imports do not change. Integrated
 initialization creates only app-owned files and never rewrites Arcane OS or SDK
 root configuration.
 
@@ -235,13 +244,14 @@ exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
 apps synthesize that descriptor from their schema-1 package plus the current
 native registry during migration.
 
-An external app's `arcane-packager.json` has three exact shared routes. They map
-the installed SDK runtime to `/arcane`, its vendored strong-type dependency to
-`/node_modules/strong-type`, and the SDK's `LICENSE`,
-`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. Development does
-not copy SDK runtime source into the app repository. Distribution materializes
-those selected SDK routes completely inside the portable artifact, so the
-finished app has no Arcane OS runtime dependency.
+An external app can use four `installed-v1` shared routes in
+`arcane-packager.json`: the installed SDK's `runtime/arcane` maps to `/arcane`,
+`browser-runtime` to `/arcane/sdk`, `runtime/strong-type` to
+`/arcane/dependencies/strong-type`, and its three license files to
+`/licenses/arcane-os`. Source serving and import-map generation read those
+installed files without creating a workspace runtime copy. Distribution copies
+the selected routes completely inside the portable artifact, preserving the
+same URLs. Existing physical `arcane/` routes retain their behavior.
 
 Release schema 1 and builder identity `arcane-app-packager-v1` remain unchanged
 because current Arcane native consumers treat them as public contracts. Native

package/docs/reference/cli.md

@@ -184,7 +184,7 @@ npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 
 ### Overview
 
-Refreshes one selected application's physical browser runtime map, generates
+Refreshes one selected application's browser runtime map, generates
 its standard browser import map, discovers every directly navigable
 `.html`/`.htm` document admitted by the selected descriptor's existing
 include/exclude rules, and commits the map artifact plus those managed documents
@@ -211,10 +211,10 @@ The generated artifact is
 `apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
 the configured entry and every other admitted browser document as `<script
 type="importmap" data-arcane-import-map>` before module loading. The complete
-physical-v1 runtime derives its entries from the installed runtime and
-browser-runtime inventories. It intentionally has no package-root mapping;
+runtime map derives its entries from the selected runtime and browser-runtime
+inventories. It intentionally has no package-root mapping;
 portable runtime subpaths such as `arcane-os/preference-store` and
-`arcane-os/speech-playback` instead map directly to their canonical projected
+`arcane-os/speech-playback` instead map directly to their canonical runtime
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
@@ -224,6 +224,15 @@ list. External and modern integrated routes require `components`, `css`,
 may omit only an optional trailing `security` include. The external license
 route remains separate and second.
 
+External applications can instead select the four ordered
+[`installed-v1` routes](protocols.md#installed-package-browser-routes) in
+`arcane-packager.json`. This reads directly from the installed SDK package and
+requires neither a workspace `arcane/` directory nor `arcane.lock.json`.
+The generated browser destinations remain `arcane/`, `arcane/sdk/`, and
+`arcane/dependencies/strong-type/`; an npm alias changes package source paths,
+not those browser URLs. The SDK version comes from that installed package.
+Existing physical workspaces and scaffold output remain supported unchanged.
+
 ### Result and safety
 
 Success returns the normal selected-workspace wrapper:
@@ -308,9 +317,12 @@ Starts one development server for one selected app and maps the exact
 workspace/runtime routes. It defaults to HTTPS on localhost; `--public` enables access
 from other devices on the network, using HTTPS by default.
 
-For an external workspace, the server exposes the selected projected
-`arcane/` root, including `arcane/sdk` and `arcane/dependencies`, alongside the
-application. Integrated workspaces retain their configured physical routes.
+For an external workspace, the server exposes the selected SDK routes alongside
+the application. `installed-v1` serves directly from the installed package
+under `/arcane`, `/arcane/sdk`, and `/arcane/dependencies/strong-type`, without
+creating a workspace runtime directory. Existing `physical-v1` workspaces serve
+their projected `arcane/` root. Integrated workspaces retain their configured
+physical routes.
 The explicit live-source SDK mapping remains unchanged and does not replace the
 installed projection.
 
@@ -504,6 +516,11 @@ shared route destinations. When selected shared content supplies no root
 Source document bases and resource URLs therefore retain their development
 layout. Packaging does not run tests or checks automatically.
 
+For `installed-v1`, the same four configured source routes supply the complete
+selected SDK content directly from `node_modules`. Only the portable output
+receives copies; no workspace `arcane/` projection is required. Its runtime URLs,
+managed import-map targets, and PWA inventory destinations match source serving.
+
 ```text
 arcane package [--app <id>] [--dry-run]
 ```

package/docs/reference/protocols.md

@@ -61,13 +61,19 @@ explicit identity fails, and the selected page then must pass exact path-relativ
 base validation.
 Included HTML with neither signal is a component fragment and remains a
 complete package file.
-`arcane-os/preference-store` and `arcane-os/speech-playback` are the two
-portable subpaths that resolve directly to canonical runtime-module namespaces
-from both Node package exports and managed browser keys;
+Public lowercase runtime subpaths resolve directly to canonical runtime-module
+namespaces from both Node package exports and managed browser keys. These
+include `arcane-os/preference-store`, `arcane-os/speech-playback`,
+`arcane-os/ai-preference-tuple`, `arcane-os/ai-preference-runtime`,
+`arcane-os/ai-provider-runtime`, `arcane-os/ai-runtime-state`,
+`arcane-os/model-definition`, `arcane-os/conversation-timebox`,
+`arcane-os/conversation-action-items`, `arcane-os/conversation-closing-report`,
+and `arcane-os/chat-records`.
 `arcane/PreferenceStore` and `arcane/SpeechPlayback` remain their established
 browser import-map names. The additional portable `arcane-os/speech-text`
 subpath owns shared speech-input cleanup and has the same
-managed browser key. There is
+managed browser key. `arcane-os/mail` remains the existing Mail aggregation.
+There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.
 Explicit host document lists use the separate root-exported
@@ -90,6 +96,68 @@ materializes the complete required SDK runtime,
 browser-runtime, and managed-import-map closure inside that app's own artifact.
 No application polls for SDK changes.
 
+## Installed-package browser routes
+
+An external application can serve and package its installed SDK directly,
+without creating a top-level `arcane/` directory or requiring
+`arcane.lock.json`. Select `installed-v1` through these four ordered routes in
+the existing schema-1 `arcane-packager.json`; no additional layout field is
+needed:
+
+```json
+{
+  "schemaVersion": 1,
+  "appsRoot": "apps",
+  "distRoot": "dist",
+  "sharedPayloads": {
+    "browser-runtime": [
+      {
+        "source": "node_modules/arcane-os/runtime/arcane",
+        "destination": "arcane",
+        "include": ["components", "css", "entities", "img", "modules"],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os/browser-runtime",
+        "destination": "arcane/sdk",
+        "include": ["."],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os/runtime/strong-type",
+        "destination": "arcane/dependencies/strong-type",
+        "include": ["."],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os",
+        "destination": "licenses/arcane-os",
+        "include": ["LICENSE", "COMMERCIAL-LICENSE.md", "NOTICE"],
+        "exclude": []
+      }
+    ]
+  }
+}
+```
+
+The first include list also accepts a final `security` entry. An npm alias such
+as `arcane-sdk` substitutes `node_modules/arcane-sdk` for the package prefix in
+all four source paths. Destinations remain unchanged. Package selection and SDK
+version come from the installed dependency, not a generated runtime lock.
+
+`arcane import-map`, `arcane dev`, packaging, and generated PWA inventories use
+the same logical destinations. Source serving and map generation read installed
+files without materializing them into the workspace. A selected portable
+package copies its complete selected resources inside the artifact, preserving
+the same browser URLs and saved managed import maps.
+
+Existing `physical-v1` configurations whose first source is `arcane` remain
+supported. The explicit materializer below still refreshes those projections,
+and scaffolding retains its existing physical layout. Selecting `installed-v1`
+does not delete any preexisting workspace files. The separate host-document
+`generateDocumentImportMaps()` API continues to accept an already materialized
+runtime; its input contract is unchanged.
+
 ## Installed SDK runtime materialization
 
 `materializeInstalledSdkRuntime()` is the Node entrypoint for refreshing one

package/docs/reference/pwa.md

@@ -108,6 +108,15 @@ app's `arcane-app.json`. Startup refreshes that app's generated
 maps and starting the server. No packaging or `dist` output is required.
 Package-only applications retain their existing descriptor workflow.
 
+With the external [`installed-v1` routes](protocols.md#installed-package-browser-routes),
+the server inventories the selected SDK directly in `node_modules`. Runtime
+resources retain their public `arcane/`, `arcane/sdk/`, and
+`arcane/dependencies/strong-type/` URLs, so offline selections use those logical
+paths rather than package filesystem paths. No workspace `arcane/` tree or
+`arcane.lock.json` is needed. Packaging uses the same route selection and copies
+the selected resources into the portable output; existing physical projections
+remain supported.
+
 Add a file or directory to `package.include` to make it part of the app's
 resources. A new file inside an already included directory needs no separate
 entry. `package.include` is an application resource selection, not a file list

package/docs/reference/sdk-api.md

@@ -5,11 +5,12 @@ The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
 `arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
-Those package subpaths are distinct from application-facing projection modules
-in the managed browser map, such as `arcane/AIProviderRuntime`,
-`arcane/AIRuntimeState`, and `arcane/ThemeBootstrap`. Applications use those
-mapped runtime modules and call `globalThis.Arcane` for capability-gated host
-behavior; they are not additional `package.json#exports` entrypoints.
+Lowercase runtime subpaths also expose existing module namespaces through both
+Node package exports and managed browser imports, as listed below. Established
+browser names such as `arcane/AIProviderRuntime`, `arcane/AIRuntimeState`, and
+`arcane/ThemeBootstrap` remain managed-map names rather than Node package
+entrypoints. Applications call `globalThis.Arcane` for capability-gated host
+behavior.
 
 This page is the canonical inventory for every JavaScript name reachable through `package.json#exports`. The same binding can appear at the root and a focused subpath; those entrypoints are listed together. The root workspace `discoverApps` and the low-level packager `discoverApps` are intentionally separate records because they are different functions.
 
@@ -19,7 +20,8 @@ This table is the Node `package.json#exports` map: it defines package
 entrypoints for SDK/tooling code. It is distinct from the generated browser
 import map that resolves application-facing `arcane/*` modules and the focused
 EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
-for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
+for the shared browser destinations used by installed-package and physical
+runtime layouts.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -36,6 +38,21 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/event-manager` | Central synchronous events, complete time-travel history, playback, and optional DOM instrumentation. |
 | `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
+| `arcane-os/ai` | Existing `AI.js` provider-neutral inference and speech namespace. |
+| `arcane-os/ai-preference-tuple` | Existing `AIPreferenceTuple.js` module namespace. |
+| `arcane-os/ai-preference-runtime` | Existing `AIPreferenceRuntime.js` module namespace. |
+| `arcane-os/ai-provider-runtime` | Existing `AIProviderRuntime.js` provider selection and lifecycle namespace. |
+| `arcane-os/ai-runtime-state` | Existing `AIRuntimeState.js` state and event namespace. |
+| `arcane-os/model-definition` | Existing `ModelDefinition.js` module namespace. |
+| `arcane-os/conversation-timebox` | Existing `ConversationTimebox.js` module namespace. |
+| `arcane-os/conversation-action-items` | Existing `ConversationActionItems.js` module namespace. |
+| `arcane-os/conversation-closing-report` | Existing `ConversationClosingReport.js` module namespace. |
+| `arcane-os/chat-records` | Existing `ChatRecords.js` module namespace. |
+| `arcane-os/app-data-scope` | Existing `AppDataScope.js` application storage scope namespace. |
+| `arcane-os/core-local-model-catalog` | Existing `CoreLocalModelCatalog.js` local model catalog namespace. |
+| `arcane-os/dbopfs-document-library` | Existing `DBOPFSDocumentLibrary.js` document storage namespace. |
+| `arcane-os/local-ai-readiness` | Existing `LocalAIReadiness.js` local AI readiness namespace. |
+| `arcane-os/ollama-model-identifier` | Existing `OllamaModelIdentifier.js` model identifier namespace. |
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
 | `arcane-os/speech-text` | Speech-input formatting cleanup for complete text and streamed chunks. |
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
@@ -45,6 +62,18 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
+These lowercase runtime-module entrypoints expose their existing exports; they
+do not duplicate the module implementations or change their platform and
+lifecycle requirements. Node resolves them inside the installed package, while
+the managed browser map resolves the same names to the selected runtime URLs.
+Node package resolution does not make browser-only operations available in
+Node: a module still needs its documented browser globals, storage, media,
+Worker, or host capabilities when its initialization or operation uses them.
+Use `arcane-os/mail` for the existing Mail aggregation rather than importing a
+private runtime file. Its package facade and managed browser entry both expose
+the canonical `MailApi.mjs` aggregation and the same Mail, outbox, and transport
+bindings.
+
 Eight JSON schemas and `package.json` are data-only export subpaths. In Node ESM, import JSON with `with {type: 'json'}`, or resolve and read it explicitly.
 
 ### Managed AI narration
@@ -1496,6 +1525,11 @@ After full runtime replacement, it writes or replaces semantic
 `arcane.lock.json` from the actual installed dependency name, package name,
 package version, alias source, and projected roots.
 
+This operation remains available for physical workspace projections. External
+applications using [installed-package routes](protocols.md#installed-package-browser-routes)
+read directly from their installed dependency and do not need to call it or
+create `arcane.lock.json` before serving, refreshing app import maps, or packaging.
+
 ### Signature and result
 
 ```text
@@ -3643,6 +3677,10 @@ certPath, keyPath, tls, signal, onEvent}` and serves one validated
 workspace application plus its complete SDK or integrated runtime. Packaged mode uses
 `{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, certPath, keyPath, tls,
 signal, onEvent}` and serves the complete selected release files.
+External source mode accepts both the installed-package route layout and the
+existing physical runtime layout. Installed-package mode serves the configured
+SDK resources directly from `node_modules` at their logical browser URLs;
+it does not create a workspace `arcane/` directory or require `arcane.lock.json`.
 `host` defaults to `127.0.0.1` and accepts an
 explicit network address or hostname. Use `0.0.0.0` for all IPv4 interfaces or
 `::` for the platform's IPv6 wildcard listeners. `port` selects the HTTPS
@@ -3866,8 +3904,10 @@ async validateWorkspace({
 
 Import it from `arcane-os`. It resolves to a validation result with
 `valid`, `workspaceMode`, `workspaceRoot`, `appId`, `appRoot`, the selected
-configuration/application, lock data, and completed checks. For an external
-workspace it additionally returns the exact installed package authority:
+configuration/application, lock data where the layout uses it, and completed
+checks. External `installed-v1` selection reads package metadata directly and
+does not require a workspace `arcane.lock.json` or runtime projection. For an
+external workspace the result additionally includes the installed package:
 
 ```javascript
 {
@@ -3876,17 +3916,17 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.18',
+    packageVersion,
     runtimeRoot,
     browserRuntimeRoot
   }
 }
 ```
 
-The dependency can be named `arcane-os` or be one exact npm alias for
-`npm:arcane-os@0.5.18`. The selected installation must still be one direct,
-physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.18`; duplicate canonical/alias declarations reject.
+The dependency can be named `arcane-os` or use an npm alias for the selected
+`arcane-os` version. The configured package source must match that declaration;
+`packageVersion` reports the installed package's version. Duplicate
+canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -17,6 +17,21 @@
     "./browser-device": "./browser-runtime/browser-device.mjs",
     "./pwa": "./browser-runtime/pwa.mjs",
     "./preference-store": "./runtime/arcane/modules/PreferenceStore.js",
+    "./ai": "./runtime/arcane/modules/AI.js",
+    "./ai-preference-tuple": "./runtime/arcane/modules/AIPreferenceTuple.js",
+    "./ai-preference-runtime": "./runtime/arcane/modules/AIPreferenceRuntime.js",
+    "./ai-provider-runtime": "./runtime/arcane/modules/AIProviderRuntime.js",
+    "./ai-runtime-state": "./runtime/arcane/modules/AIRuntimeState.js",
+    "./model-definition": "./runtime/arcane/modules/ModelDefinition.js",
+    "./conversation-timebox": "./runtime/arcane/modules/ConversationTimebox.js",
+    "./conversation-action-items": "./runtime/arcane/modules/ConversationActionItems.js",
+    "./conversation-closing-report": "./runtime/arcane/modules/ConversationClosingReport.js",
+    "./chat-records": "./runtime/arcane/modules/ChatRecords.js",
+    "./app-data-scope": "./runtime/arcane/modules/AppDataScope.js",
+    "./core-local-model-catalog": "./runtime/arcane/modules/CoreLocalModelCatalog.js",
+    "./dbopfs-document-library": "./runtime/arcane/modules/DBOPFSDocumentLibrary.js",
+    "./local-ai-readiness": "./runtime/arcane/modules/LocalAIReadiness.js",
+    "./ollama-model-identifier": "./runtime/arcane/modules/OllamaModelIdentifier.js",
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
@@ -69,7 +84,7 @@
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
-    "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
+    "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",

package/runtime/arcane/modules/MailApi.mjs

@@ -0,0 +1,19 @@
+export {
+    default,
+    default as Mail,
+    resolveMailConfig
+} from './Mail.js';
+export {
+    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
+    MAIL_OUTBOX_PROTOCOL,
+    MAIL_OUTBOX_STATES,
+    MAIL_OUTBOX_TABLE,
+    MailOutbox,
+    createMailOutbox
+} from './MailOutbox.mjs';
+export {
+    MailTransportError,
+    normalizeMailEndpoint,
+    sendMailReport,
+    serializeMailReport
+} from './MailTransport.mjs';

package/src/dev-server.mjs

@@ -6,6 +6,7 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
+import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
 import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
 import {createEventQueue} from './event-queue.mjs';
@@ -436,6 +437,7 @@ function sharedPathAllowed(relative,route){
     });
     if(excluded)return false;
     return route.include.some(item=>{
+        if(item==='.')return true;
         const candidate=inventoryKey(item);
         return comparable===candidate||comparable.startsWith(`${candidate}/`);
     });
@@ -471,11 +473,16 @@ async function sourceRoutes(workspaceRoot,appId,{
             mappings:[appMapping,...sdkSource.mappings]
         };
     }
-    if(resolved.config.workspaceMode==='integrated'){
+    if(resolved.config.workspaceMode==='integrated'
+        ||resolved.config.browserRuntimeLayout==='installed-v1'){
+        const installed=resolved.config.browserRuntimeLayout==='installed-v1'
+            ?await readInstalledSdkLayout(resolved.workspaceRoot,resolved.config)
+            :null;
         return {
             workspaceRoot:resolved.workspaceRoot,
-            workspaceMode:'integrated',
+            workspaceMode:resolved.config.workspaceMode,
             config:resolved.config,
+            ...(installed?{installed}:{}),
             appId:resolved.appId,
             app:resolved.app.manifest,
             startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
@@ -579,7 +586,7 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
             }
         }
         for (const selected of mapping.include ?? ['']) {
-            await visitSourceResource(selected ? selected.split('/') : []);
+            await visitSourceResource(selected && selected!=='.' ? selected.split('/') : []);
         }
     }
     const origin = 'http://arcane.invalid';
@@ -866,7 +873,7 @@ async function startOwnedDevServer({
     const mappings=deterministicMappings(routeSet.mappings);
     const versionPath = mode === 'source'
         ? sdkRuntimeSourceRoot === undefined
-            ? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
+            ? routeSet.installed?.versionPath ?? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
             : path.join(routeSet.runtime.sourceRoot, 'package.json')
         : undefined;
     const [generatorInputs, initialAssetVersion, versionInput] = await Promise.all(
@@ -897,6 +904,9 @@ async function startOwnedDevServer({
     );
     async function selectedAssetVersion(){
         if(mode!=='source')return undefined;
+        if(routeSet.installed)return JSON.parse(await readFile(
+            routeSet.installed.versionPath,'utf8'
+        )).version;
         return sdkRuntimeSourceRoot===undefined
             ?readWorkspaceAssetVersion(routeSet.workspaceRoot)
             :JSON.parse(await readFile(

package/src/import-map.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {pathToFileURL} from 'node:url';
 import {SDK_VERSION} from './constants.mjs';
 import {listRuntimeFiles} from './runtime.mjs';
+import {readInstalledSdkLayout,installedRuntimeFiles,installedRuntimeTarget} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -19,7 +20,23 @@ const SDK_BROWSER_AI_ENTRY='sdk/ai/browser-wasm.mjs';
 const SDK_BROWSER_SPEECH_ENTRY='sdk/ai/browser-speech.mjs';
 const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
     ['arcane-os/preference-store','modules/PreferenceStore.js'],
-    ['arcane-os/speech-playback','modules/SpeechPlayback.js']
+    ['arcane-os/speech-playback','modules/SpeechPlayback.js'],
+    ['arcane-os/ai','modules/AI.js'],
+    ['arcane-os/ai-preference-tuple','modules/AIPreferenceTuple.js'],
+    ['arcane-os/ai-preference-runtime','modules/AIPreferenceRuntime.js'],
+    ['arcane-os/ai-provider-runtime','modules/AIProviderRuntime.js'],
+    ['arcane-os/ai-runtime-state','modules/AIRuntimeState.js'],
+    ['arcane-os/model-definition','modules/ModelDefinition.js'],
+    ['arcane-os/conversation-timebox','modules/ConversationTimebox.js'],
+    ['arcane-os/conversation-action-items','modules/ConversationActionItems.js'],
+    ['arcane-os/conversation-closing-report','modules/ConversationClosingReport.js'],
+    ['arcane-os/chat-records','modules/ChatRecords.js'],
+    ['arcane-os/app-data-scope','modules/AppDataScope.js'],
+    ['arcane-os/core-local-model-catalog','modules/CoreLocalModelCatalog.js'],
+    ['arcane-os/dbopfs-document-library','modules/DBOPFSDocumentLibrary.js'],
+    ['arcane-os/local-ai-readiness','modules/LocalAIReadiness.js'],
+    ['arcane-os/ollama-model-identifier','modules/OllamaModelIdentifier.js'],
+    ['arcane-os/mail','modules/MailApi.mjs']
 ]);
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
@@ -1436,9 +1453,10 @@ async function physicalRuntime(workspaceRoot,signal){
 }
 
 async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
+    const installed=await readInstalledSdkLayout(resolvedWorkspace);
     const [runtime,version]=await Promise.all([
-        physicalRuntime(resolvedWorkspace,signal),
-        pwaEnabled?null:readWorkspaceAssetVersion(resolvedWorkspace)
+        installed?installedRuntimeFiles(resolvedWorkspace,installed,signal):physicalRuntime(resolvedWorkspace,signal),
+        pwaEnabled?null:installed?.version??readWorkspaceAssetVersion(resolvedWorkspace)
     ]);
     const built=await buildImportMap({files:runtime.files,signal,version});
     const json=`${JSON.stringify({imports:built.imports},null,2).replaceAll('<','\\u003c')}\n`;
@@ -1446,6 +1464,8 @@ async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
 }
 
 export async function readWorkspaceAssetVersion(workspaceRoot){
+    const installed=await readInstalledSdkLayout(workspaceRoot);
+    if(installed)return installed.version;
     let source;
     try{source=await readFileFromDisk(path.join(workspaceRoot,'arcane.lock.json'),'utf8');}
     catch(error){
@@ -2434,10 +2454,17 @@ export async function readApplicationTestImportMapContext({
         ||is.array(document.imports)){
         fail('Application test import-map artifact must contain an imports object.');
     }
+    const installed=await readInstalledSdkLayout(resolvedWorkspaceRoot);
+    const imports=installed?Object.fromEntries(Object.entries(document.imports).map(
+        function installedApplicationTestTarget([specifier,target]){
+            return [specifier,is.string(target)&&target.startsWith('./')
+                ?`./${installedRuntimeTarget(target.slice(2),installed)}`:target];
+        }
+    )):document.imports;
     return createApplicationTestImportMapContext({
         applicationRoot:resolvedWorkspaceRoot,
         boundary:'source',
-        imports:document.imports,
+        imports,
         signal
     });
 }

package/src/mail-api.mjs

@@ -1,19 +1,2 @@
-export {
-    default,
-    default as Mail,
-    resolveMailConfig
-} from '../runtime/arcane/modules/Mail.js';
-export {
-    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
-    MAIL_OUTBOX_PROTOCOL,
-    MAIL_OUTBOX_STATES,
-    MAIL_OUTBOX_TABLE,
-    MailOutbox,
-    createMailOutbox
-} from '../runtime/arcane/modules/MailOutbox.mjs';
-export {
-    MailTransportError,
-    normalizeMailEndpoint,
-    sendMailReport,
-    serializeMailReport
-} from '../runtime/arcane/modules/MailTransport.mjs';
+export {default} from '../runtime/arcane/modules/MailApi.mjs';
+export * from '../runtime/arcane/modules/MailApi.mjs';

package/src/packager/core.mjs

@@ -136,12 +136,13 @@ function isGlobLike(value){
     return /[*?\[\]{}]/u.test(value);
 }
 
-function validatePathList(value,label,{required=false}={}){
+function validatePathList(value,label,{required=false,allowRoot=false}={}){
     if(!is.array(value)||(required&&value.length===0)){
         fail(`${label} must be ${required?'a non-empty':'an'} array of literal relative paths.`);
     }
     const normalized=value.map((entry,index)=>{
-        const item=normalizeRelativePath(entry,`${label}[${index}]`);
+        const item=allowRoot?normalizeRelativeRoot(entry,`${label}[${index}]`)
+            :normalizeRelativePath(entry,`${label}[${index}]`);
         if(isGlobLike(item))fail(`${label}[${index}] must be literal; directories include descendants.`);
         return item;
     });
@@ -151,7 +152,8 @@ function validatePathList(value,label,{required=false}={}){
     if(required){
         for(let left=0;left<normalized.length;left+=1){
             for(let right=left+1;right<normalized.length;right+=1){
-                if(sameOrDescendant(normalized[left],normalized[right])
+                if(normalized[left]==='.'||normalized[right]==='.'
+                    ||sameOrDescendant(normalized[left],normalized[right])
                     ||sameOrDescendant(normalized[right],normalized[left])){
                     fail(`${label} has overlapping paths: ${normalized[left]} and ${normalized[right]}`);
                 }
@@ -256,7 +258,7 @@ function validateSharedRoute(route,label){
     assertOnlyKeys(route,new Set(['source','destination','include','exclude']),label);
     const source=normalizeRelativeRoot(route.source,`${label}.source`);
     const destination=normalizeRelativeRoot(route.destination,`${label}.destination`);
-    const include=validatePathList(route.include,`${label}.include`,{required:true});
+    const include=validatePathList(route.include,`${label}.include`,{required:true,allowRoot:true});
     const exclude=validatePathList(route.exclude??[],`${label}.exclude`);
     if(source==='.'||source==='apps'||source.startsWith('apps/')
         ||source==='dist'||source.startsWith('dist/')||source==='node_modules'
@@ -421,7 +423,7 @@ async function loadContext(requestedWorkspaceRoot,appId){
 }
 
 function destinationJoin(root,relative){
-    return root==='.'?relative:`${root}/${relative}`;
+    return relative==='.'?root:root==='.'?relative:`${root}/${relative}`;
 }
 
 function appPackagePath(context, relative) {
@@ -442,12 +444,13 @@ async function collectSelectedPath({
     records,
     destinations,
     signal,
-    label
+    label,
+    allowRoot=false
 }){
     throwIfAborted(signal);
     if(isExcluded(selected,excludes))return;
     if(reject(selected))fail(`${label} selects a reserved private or generated path: ${selected}.`);
-    const absolute=resolveInside(sourceRoot,selected,label);
+    const absolute=resolveInside(sourceRoot,selected,label,{allowRoot});
     let info;
     try{info=await lstat(absolute);}
     catch(error){
@@ -455,15 +458,16 @@ async function collectSelectedPath({
         throw error;
     }
     if(info.isSymbolicLink())fail(`${label} contains a symbolic link or junction: ${selected}.`);
+    if(selected==='.'&&!info.isDirectory())fail(`${label} root selection must be a directory.`);
     if(info.isDirectory()){
         const entries=await readdir(absolute,{withFileTypes:true});
         entries.sort((left,right)=>compareText(left.name,right.name));
         for(const entry of entries){
-            const child=`${selected}/${entry.name}`;
+            const child=destinationJoin(selected,entry.name);
             await collectSelectedPath({
                 sourceRoot,
                 selected:child,
-                destination:`${destination}/${entry.name}`,
+                destination:destinationJoin(destination,entry.name),
                 excludes,
                 reject,
                 records,
@@ -515,7 +519,8 @@ async function collectPackageRecords(context,{signal}={}){
                     records,
                     destinations,
                     signal,
-                    label:`sharedPayloads.${sharedId}`
+                    label:`sharedPayloads.${sharedId}`,
+                    allowRoot:true
                 });
             }
         }

package/src/sdk-runtime-layout.mjs

@@ -0,0 +1,99 @@
+import Is from 'strong-type';
+import {readFile,readdir} from 'node:fs/promises';
+import path from 'node:path';
+
+const is=new Is(false);
+
+// The browser URLs stay the same; only the source of their files changes.
+export function installedSdkRoutes(packageSource,{security=false}={}){
+    return [
+        {
+            source:`${packageSource}/runtime/arcane`,destination:'arcane',
+            include:['components','css','entities','img','modules',...(security?['security']:[])],exclude:[]
+        },
+        {
+            source:`${packageSource}/browser-runtime`,destination:'arcane/sdk',
+            include:['.'],exclude:[]
+        },
+        {
+            source:`${packageSource}/runtime/strong-type`,destination:'arcane/dependencies/strong-type',
+            include:['.'],exclude:[]
+        },
+        {
+            source:packageSource,destination:'licenses/arcane-os',
+            include:['LICENSE','COMMERCIAL-LICENSE.md','NOTICE'],exclude:[]
+        }
+    ];
+}
+
+export function installedSdkPackageSource(config){
+    const routes=config?.sharedPayloads?.['browser-runtime'];
+    if(!is.array(routes)||routes.length!==4)return null;
+    const source=routes[3]?.source;
+    if(!is.string(source)||!/^node_modules\/(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(source))return null;
+    const expected=installedSdkRoutes(source,{security:routes[0]?.include?.at(-1)==='security'});
+    return routes.every(function matchesInstalledRoute(route,index){
+        const wanted=expected[index];
+        return route?.source===wanted.source&&route?.destination===wanted.destination
+            &&is.array(route.include)&&route.include.length===wanted.include.length
+            &&route.include.every(function matchesSelectedPath(value,item){return value===wanted.include[item];})
+            &&(route.exclude===undefined||(is.array(route.exclude)&&route.exclude.length===0));
+    })?source:null;
+}
+
+export async function readInstalledSdkLayout(workspaceRoot,config){
+    if(config===undefined){
+        try{config=JSON.parse(await readFile(path.join(workspaceRoot,'arcane-packager.json'),'utf8'));}
+        catch(error){if(error.code==='ENOENT')return null;throw error;}
+    }
+    const packageSource=installedSdkPackageSource(config);
+    if(packageSource===null)return null;
+    const packageRoot=path.join(workspaceRoot,...packageSource.split('/'));
+    const versionPath=path.join(packageRoot,'package.json');
+    const manifest=JSON.parse(await readFile(versionPath,'utf8'));
+    if(manifest.name!=='arcane-os'||!is.string(manifest.version)||!manifest.version){
+        const error=new Error('The installed SDK runtime must identify its arcane-os package version.');
+        error.code='ARCANE_WORKSPACE_INVALID';
+        throw error;
+    }
+    return {packageSource,packageRoot,versionPath,version:manifest.version,routes:config.sharedPayloads['browser-runtime']};
+}
+
+export async function installedRuntimeFiles(workspaceRoot,layout,signal){
+    const files=[];
+    async function visit(directory,logical){
+        signal?.throwIfAborted();
+        const entries=await readdir(directory,{withFileTypes:true});
+        for(const entry of entries){
+            signal?.throwIfAborted();
+            const relative=logical?`${logical}/${entry.name}`:entry.name;
+            if(entry.isDirectory())await visit(path.join(directory,entry.name),relative);
+            else if(entry.isFile())files.push(relative);
+        }
+    }
+    for(const route of layout.routes){
+        if(route.destination!=='arcane'&&!route.destination.startsWith('arcane/'))continue;
+        const prefix=route.destination==='arcane'?'':route.destination.slice('arcane/'.length);
+        for(const selected of route.include){
+            const suffix=selected==='.'?'':selected;
+            await visit(
+                path.join(workspaceRoot,...route.source.split('/'),suffix),
+                [prefix,suffix].filter(Boolean).join('/')
+            );
+        }
+    }
+    return {files:files.sort()};
+}
+
+export function installedRuntimeTarget(relative,layout){
+    for(const route of [...layout.routes].sort(function longestDestinationFirst(left,right){
+        return right.destination.length-left.destination.length;
+    })){
+        if(!relative.startsWith(`${route.destination}/`))continue;
+        const suffix=relative.slice(route.destination.length+1);
+        if(route.include.some(function includesRuntimeTarget(selected){
+            return selected==='.'||suffix===selected||suffix.startsWith(`${selected}/`);
+        }))return `${route.source}/${suffix}`;
+    }
+    return relative;
+}

package/src/workspace.mjs

@@ -9,6 +9,7 @@ import {
 import {loadAppDescriptor} from './app-descriptor.mjs';
 import {SDK_NAME as EXPECTED_SDK_NAME} from './constants.mjs';
 import {inspectImportMapHtml} from './import-map.mjs';
+import {installedSdkPackageSource} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -159,6 +160,13 @@ function classifyRootConfig(config){
     const validated=validatePackagerRootConfig(config,ROOT_CONFIG_NAME);
     const routes=validated.sharedPayloads['browser-runtime'];
     if(!is.array(routes))fail(`${ROOT_CONFIG_NAME} must define browser-runtime routes.`);
+    const installedPackageSource=installedSdkPackageSource(validated);
+    if(installedPackageSource!==null){
+        return {
+            ...validated,workspaceMode:'external',browserRuntimeLayout:'installed-v1',
+            sdkPackageSource:installedPackageSource
+        };
+    }
     const externalPackageSource=routes.length===2
         &&dependencyNameForSdkPackageSource(routes[1]?.source)!==null
         ?routes[1].source