@happyvertical/smrt-planner 0.0.1 → 0.0.2

package/dist/ai/state.svelte.d.ts

@@ -1,7 +1,7 @@
 import { AssistantSession, type SessionOptions } from '../assistant/session.svelte.ts';
 import { type VoiceOptions, VoiceSession } from '../assistant/voice.svelte.ts';
 import { ByoModel } from '../inference/byo.svelte.ts';
-import { type ConfigResult, type InferenceConfig } from '../inference/config.ts';
+import { type ConfigResult, type InferenceConfig, type InferenceMode } from '../inference/config.ts';
 import { type CapabilitySummary } from './status.ts';
 /** UI choices that are not part of the cookbook. */
 export interface AiPrefs {
@@ -59,7 +59,9 @@ export declare class AiState {
     speaking: boolean;
     /** Where the model runs, from `planner.config.json` or the `inference` prop. */
     inference: InferenceConfig;
-    /** Set when the config was unusable and `browser` is used instead. */
+    /** Modes this policy exposes. Manual is always available for a multi-mode policy. */
+    availableModes: InferenceMode[];
+    /** Set when the config was unusable and inference fails closed to manual. */
     notice: string;
     /** The visitor's own endpoint (byo mode only). */
     byo: ByoModel | null;
@@ -84,10 +86,13 @@ export declare class AiState {
     /**
      * Apply the inference config. `host` is ready at once (nothing to download);
      * `byo` is ready once the visitor has connected an endpoint on the AI page;
-     * `browser` is today's WebLLM. An unusable config arrives as `browser` with
-     * a `notice`.
+     * `browser` is today's WebLLM. An unusable config arrives as `manual` with a
+     * `notice`.
      */
     configure(result: ConfigResult): void;
+    /** Change providers only after a visitor selects one from the configured policy. */
+    selectInference(mode: InferenceMode): void;
+    private applyMode;
     private syncByo;
     private decideFirstRun;
     /** Before hydration every capability reads as not set up, as on the server. */

package/dist/ai/state.svelte.js

@@ -63,7 +63,9 @@ export class AiState {
     speaking = $state(false);
     /** Where the model runs, from `planner.config.json` or the `inference` prop. */
     inference = $state(DEFAULT_INFERENCE);
-    /** Set when the config was unusable and `browser` is used instead. */
+    /** Modes this policy exposes. Manual is always available for a multi-mode policy. */
+    availableModes = $state(['browser']);
+    /** Set when the config was unusable and inference fails closed to manual. */
     notice = $state('');
     /** The visitor's own endpoint (byo mode only). */
     byo = $state(null);
@@ -119,36 +121,60 @@ export class AiState {
     /**
      * Apply the inference config. `host` is ready at once (nothing to download);
      * `byo` is ready once the visitor has connected an endpoint on the AI page;
-     * `browser` is today's WebLLM. An unusable config arrives as `browser` with
-     * a `notice`.
+     * `browser` is today's WebLLM. An unusable config arrives as `manual` with a
+     * `notice`.
      */
     configure(result) {
         const { config, notice } = result;
         this.pendingConfig = false;
         this.inference = config;
         this.notice = notice ?? '';
-        this.session.setMode(config.mode);
-        this.byo = null;
-        if (config.mode === 'host' && config.host) {
+        const configured = [config.mode, ...(config.alternatives ?? [])];
+        this.availableModes = [
+            ...configured,
+            ...(config.alternatives?.length && !configured.includes('manual')
+                ? ['manual']
+                : []),
+        ];
+        this.byo = configured.includes('byo')
+            ? new ByoModel({
+                storage: this.options.storage,
+                credentialPersistence: config.credentialPersistence,
+                presets: config.byo?.presets,
+                fetch: this.options.fetch,
+                onChange: () => this.syncByo(),
+            })
+            : null;
+        this.applyMode(config.mode);
+        if (this.hydrated)
+            this.decideFirstRun();
+    }
+    /** Change providers only after a visitor selects one from the configured policy. */
+    selectInference(mode) {
+        if (!this.availableModes.includes(mode) || mode === this.inference.mode) {
+            return;
+        }
+        this.inference = { ...this.inference, mode };
+        this.notice = '';
+        this.applyMode(mode);
+    }
+    applyMode(mode) {
+        this.session.setMode(mode);
+        if (mode === 'host' && this.inference.host) {
             const { controller, store, settings, theme } = this.options.session;
             const plan = controller ?? createSliceController({ store, settings, theme });
             this.session.useRemote(createHostChat({
-                endpoint: config.host.endpoint,
+                endpoint: this.inference.host.endpoint,
                 snapshot: () => plan.snapshot(),
                 fetch: this.options.fetch,
             }), 'Server');
         }
-        else if (config.mode === 'byo') {
-            this.byo = new ByoModel({
-                storage: this.options.storage,
-                presets: config.byo?.presets,
-                fetch: this.options.fetch,
-                onChange: () => this.syncByo(),
-            });
+        else if (mode === 'byo') {
             this.syncByo();
         }
-        if (this.hydrated)
-            this.decideFirstRun();
+        else if (mode === 'manual') {
+            this.session.useRemote(null, '');
+        }
     }
     syncByo() {
         const byo = this.byo;
@@ -160,6 +186,7 @@ export class AiState {
         // A host's server needs nothing set up, so the form has nothing to ask for.
         this.firstRun =
             this.inference.mode !== 'host' &&
+                this.inference.mode !== 'manual' &&
                 needsFirstRunSetup({
                     thinkDownloaded: this.session.prefs.consented.length > 0 ||
                         this.session.status === 'ready',
@@ -194,6 +221,9 @@ export class AiState {
     }
     /** One sentence on where what the visitor types goes, for the AI page. */
     get privacyNote() {
+        if (this.inference.mode === 'manual') {
+            return 'Inference is off. Planning, validation and export still work without a model.';
+        }
         if (this.inference.mode === 'host') {
             return "Your messages and a short summary of your plan go to this site's server. Voice typing and reading aloud stay on this device.";
         }

package/dist/ai/status.js

@@ -7,6 +7,14 @@ export function deriveCapabilities(input) {
 }
 function thinkSummary(t) {
     const base = { id: 'think', name: 'Think' };
+    if (t.mode === 'manual') {
+        return {
+            ...base,
+            state: 'off',
+            label: 'Think: inference off',
+            where: 'Off',
+        };
+    }
     if (t.mode === 'host') {
         return {
             ...base,

package/dist/assistant/session.svelte.d.ts

@@ -52,6 +52,7 @@ export declare class AssistantSession {
     private loaded;
     private chat;
     private abort;
+    private loadGeneration;
     private readonly options;
     constructor(options: SessionOptions);
     /**

package/dist/assistant/session.svelte.js

@@ -40,6 +40,7 @@ export class AssistantSession {
     loaded = null;
     chat = null;
     abort = null;
+    loadGeneration = 0;
     options;
     constructor(options) {
         this.options = options;
@@ -65,7 +66,9 @@ export class AssistantSession {
                 ? 'Connect your model on the AI page first, then I can help. The cards on the Planner page work without one.'
                 : this.mode === 'host'
                     ? 'The assistant is not available right now. The cards on the Planner page work without it.'
-                    : 'Download a model first, then I can help. The cards on the Planner page work without one.',
+                    : this.mode === 'manual'
+                        ? 'Inference is off. The cards on the Planner page work without it.'
+                        : 'Download a model first, then I can help. The cards on the Planner page work without one.',
             onReply: (text) => options.onReply?.(text),
         });
     }
@@ -74,14 +77,18 @@ export class AssistantSession {
      * download; the chat is set with `useRemote`.
      */
     setMode(mode) {
+        if (mode !== this.mode)
+            this.unload();
         this.mode = mode;
         if (mode !== 'browser') {
-            this.unload();
             this.status = 'idle';
         }
         else if (!(this.options.webgpu ?? isWebGPUAvailable)()) {
             this.status = 'unsupported';
         }
+        else {
+            this.status = 'idle';
+        }
     }
     /** The remote chat model, or null when none is connected (byo, before setup). */
     useRemote(chat, label) {
@@ -112,11 +119,16 @@ export class AssistantSession {
         this.error = '';
         this.progress = { progress: 0, text: 'Starting' };
         const abort = new AbortController();
+        const generation = ++this.loadGeneration;
         this.abort = abort;
         try {
             const loaded = await loadModel(modelId, (report) => {
                 this.progress = report;
             }, abort.signal, this.options.host ?? browserHost);
+            if (generation !== this.loadGeneration || this.mode !== 'browser') {
+                loaded.dispose();
+                return;
+            }
             this.loaded = loaded;
             // Consent is recorded only once the download completed: a cancelled or
             // failed attempt must show the size and memory warning again.
@@ -133,6 +145,8 @@ export class AssistantSession {
             this.status = 'ready';
         }
         catch (error) {
+            if (generation !== this.loadGeneration)
+                return;
             if (abort.signal.aborted) {
                 this.status = 'idle';
             }
@@ -142,7 +156,8 @@ export class AssistantSession {
             }
         }
         finally {
-            this.abort = null;
+            if (generation === this.loadGeneration)
+                this.abort = null;
         }
     }
     /** Stop a download in progress. */
@@ -152,7 +167,10 @@ export class AssistantSession {
     /** Free the model, for example to choose another. */
     unload() {
         // A load in progress is aborted too, which terminates its worker.
-        this.abort?.abort();
+        this.loadGeneration += 1;
+        const abort = this.abort;
+        this.abort = null;
+        abort?.abort();
         this.transport.abort();
         this.loaded?.dispose();
         this.loaded = null;

package/dist/components/AiSetup.svelte

@@ -42,6 +42,12 @@ const byo = $derived(aiState.byo);
 const thinkWhere = $derived(
   summaries.find((s) => s.id === 'think')?.where ?? '',
 );
+const modeLabel = {
+  manual: 'Manual planning',
+  byo: 'Your model',
+  browser: 'In-browser model (WebLLM)',
+  host: "This site's server",
+} as const;
 
 const model = $derived(getModel(session.prefs.modelId));
 // A roomy graphics card can run the smarter model; it is only suggested, the
@@ -84,7 +90,28 @@ const handsFreeAvailable = $derived(voice.status === 'ready');
           </p>
         </div>
       </header>
-      {#if mode === 'host'}
+      {#if aiState.availableModes.length > 1}
+        <label>
+          Assistant mode
+          <Select
+            value={mode}
+            onchange={(event) =>
+              aiState.selectInference(event.currentTarget.value as keyof typeof modeLabel)}
+          >
+            {#each aiState.availableModes as option (option)}
+              <option value={option}>{modeLabel[option]}</option>
+            {/each}
+          </Select>
+        </label>
+        <p class="meta">Changing modes happens only when you choose it here.</p>
+      {/if}
+      {#if mode === 'manual'}
+        <p class="status">Inference off</p>
+        <p class="meta">
+          Build, edit, validate and export your cookbook without a model. No
+          provider is contacted and no browser model is downloaded.
+        </p>
+      {:else if mode === 'host'}
         <p class="status">Server</p>
         <p class="meta">
           This site's server answers the assistant. What you type, and a short
@@ -146,7 +173,9 @@ const handsFreeAvailable = $derived(voice.status === 'ready');
             </p>
           {/if}
           <p class="meta">
-            Stored only in this browser, and sent only to {byo.baseUrl || 'the address above'} (https, or this computer).
+            {aiState.inference.credentialPersistence === 'memory'
+              ? 'Kept only in this tab until reload'
+              : 'Stored only in this browser'}, and sent only to {byo.baseUrl || 'the address above'} (https, or this computer).
             <button class="link" type="button" onclick={() => byo.forgetKey()}>
               Forget the key
             </button>

package/dist/components/BrowserAssistant.svelte

@@ -33,13 +33,15 @@ const voice = $derived(aiState.voice);
 const model = $derived(getModel(session.prefs.modelId));
 const dataSource = useDataSource();
 const thinkName = $derived(
-  session.mode === 'browser'
-    ? model
-      ? shortLabel(model)
-      : ''
-    : session.mode === 'host'
-      ? 'Server'
-      : session.remoteLabel,
+  session.mode === 'manual'
+    ? 'Off'
+    : session.mode === 'browser'
+      ? model
+        ? shortLabel(model)
+        : ''
+      : session.mode === 'host'
+        ? 'Server'
+        : session.remoteLabel,
 );
 
 // Applying a cookbook runs the Cookbooks tab's path, with the cookbook's own
@@ -192,7 +194,9 @@ $effect(() => {
       <h2>Assistant</h2>
       <p>
         Describe your business and an assistant adds the matching recipes.
-        {aiState.inference.mode === 'browser'
+        {aiState.inference.mode === 'manual'
+          ? 'Inference is off. The Planner page still works without a model.'
+          : aiState.inference.mode === 'browser'
           ? 'It runs on your own device, so nothing you type leaves this page.'
           : aiState.privacyNote}
       </p>

package/dist/core/app.d.ts

@@ -1,12 +1,37 @@
+import type { InferenceConfig } from '../inference/config.ts';
+import type { KitchenEndpoint } from '../kitchen/client.ts';
 /**
- * Absolute path of the prerendered static planner app inside this package
- * (`app/`, built with the planner's relative base, so it works at `/` and at
- * any sub-path). Node only; kept out of `./core` so that entry stays free of
- * Node built-ins.
- *
- * Serve the files from here, and write your own `planner.config.json` next to
- * its `index.html` (copy the directory, or answer that one path yourself).
+ * Absolute path of the root-built prerendered planner app inside this package.
+ * Node only; kept out of `./core` so that entry stays free of Node built-ins.
+ * Serve it at `/`, or use `materializeApp` for a supported subpath artifact.
  */
 export declare const appDir: string;
-/** Absolute path of one file in the app, e.g. `appFile('planner.config.json')`. */
+/** Absolute path of one packaged app file, e.g. `appFile('index.html')`. */
 export declare function appFile(relativePath: string): string;
+export interface PlannerAppConfig {
+    inference?: InferenceConfig;
+    kitchen?: KitchenEndpoint;
+}
+export interface MaterializeAppOptions {
+    /** New or empty directory that receives the app root. */
+    outDir: string;
+    /** Canonical mount prefix: leading slash, no trailing slash, e.g. `/plan`. */
+    basePath: string;
+    /** Written as `planner.config.json` after validation and normalization. */
+    config: PlannerAppConfig;
+}
+export interface MaterializedApp {
+    outDir: string;
+    configFile: string;
+    fallbackFile: string;
+}
+/** Validate and canonicalize a non-root app mount prefix. */
+export declare function normalizeAppBasePath(basePath: string): string;
+/** Validate config strictly enough for an immutable public artifact. */
+export declare function normalizePlannerAppConfig(config: PlannerAppConfig): PlannerAppConfig;
+/**
+ * Copy the published static app into a deterministic, prefix-safe deployment
+ * artifact. The copy is assembled beside `outDir` and renamed only after its
+ * fallback and config validate, so callers never receive a partial tree.
+ */
+export declare function materializeApp(options: MaterializeAppOptions): MaterializedApp;

package/dist/core/app.js

@@ -1,15 +1,119 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { validateInferenceConfig } from "../inference/config.js";
+import { parseKitchenConfig } from "../kitchen/client.js";
 /**
- * Absolute path of the prerendered static planner app inside this package
- * (`app/`, built with the planner's relative base, so it works at `/` and at
- * any sub-path). Node only; kept out of `./core` so that entry stays free of
- * Node built-ins.
- *
- * Serve the files from here, and write your own `planner.config.json` next to
- * its `index.html` (copy the directory, or answer that one path yourself).
+ * Absolute path of the root-built prerendered planner app inside this package.
+ * Node only; kept out of `./core` so that entry stays free of Node built-ins.
+ * Serve it at `/`, or use `materializeApp` for a supported subpath artifact.
  */
 export const appDir = fileURLToPath(new URL('../../app/', import.meta.url));
-/** Absolute path of one file in the app, e.g. `appFile('planner.config.json')`. */
+/** Absolute path of one packaged app file, e.g. `appFile('index.html')`. */
 export function appFile(relativePath) {
     return fileURLToPath(new URL(relativePath, new URL('../../app/', import.meta.url)));
 }
+const sensitiveName = /^(?:api[-_]?key|key|token|authorization|secret|password)$/i;
+/** Validate and canonicalize a non-root app mount prefix. */
+export function normalizeAppBasePath(basePath) {
+    if (typeof basePath !== 'string' ||
+        !/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/.test(basePath) ||
+        basePath.split('/').some((segment) => segment === '.' || segment === '..')) {
+        throw new Error('basePath must start with /, contain URL-safe path segments, and have no trailing slash');
+    }
+    return basePath;
+}
+function assertCredentialFree(value, path = 'config') {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            assertCredentialFree(entry, `${path}[${index}]`);
+        });
+        return;
+    }
+    for (const [name, entry] of Object.entries(value)) {
+        if (sensitiveName.test(name)) {
+            throw new Error(`${path}.${name} is a credential field and cannot be built into the app`);
+        }
+        assertCredentialFree(entry, `${path}.${name}`);
+    }
+}
+/** Validate config strictly enough for an immutable public artifact. */
+export function normalizePlannerAppConfig(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('config must be an object');
+    }
+    const unknown = Object.keys(config).filter((name) => name !== 'inference' && name !== 'kitchen');
+    if (unknown.length)
+        throw new Error(`unknown app config field: ${unknown[0]}`);
+    assertCredentialFree(config);
+    const inference = validateInferenceConfig({
+        inference: config.inference,
+    });
+    if (inference.notice)
+        throw new Error(inference.notice);
+    let kitchen;
+    if (config.kitchen !== undefined) {
+        kitchen = parseKitchenConfig(config.kitchen);
+        if (!kitchen) {
+            throw new Error('kitchen.endpoint must be a usable http(s) URL');
+        }
+    }
+    return {
+        inference: inference.config,
+        ...(kitchen ? { kitchen } : {}),
+    };
+}
+function patchFallback(file, basePath) {
+    const source = readFileSync(file, 'utf8');
+    if (!source.includes('/_app/') || !/base:\s*""/.test(source)) {
+        throw new Error('packaged 404.html does not match the supported root fallback');
+    }
+    const patched = source
+        .replaceAll('/_app/', `${basePath}/_app/`)
+        .replace(/base:\s*""/, `base: ${JSON.stringify(basePath)}`);
+    if (patched.includes('"/_app/') || /base:\s*""/.test(patched)) {
+        throw new Error('could not make the fallback prefix-safe');
+    }
+    writeFileSync(file, patched);
+}
+/**
+ * Copy the published static app into a deterministic, prefix-safe deployment
+ * artifact. The copy is assembled beside `outDir` and renamed only after its
+ * fallback and config validate, so callers never receive a partial tree.
+ */
+export function materializeApp(options) {
+    const basePath = normalizeAppBasePath(options.basePath);
+    const config = normalizePlannerAppConfig(options.config);
+    const outDir = resolve(options.outDir);
+    const source = resolve(appDir);
+    const relation = relative(source, outDir);
+    if (!relation || (!relation.startsWith(`..${sep}`) && relation !== '..')) {
+        throw new Error('outDir must be outside the packaged app directory');
+    }
+    if (existsSync(outDir)) {
+        if (!statSync(outDir).isDirectory() || readdirSync(outDir).length > 0) {
+            throw new Error('outDir must be new or empty');
+        }
+    }
+    mkdirSync(dirname(outDir), { recursive: true });
+    const temporary = mkdtempSync(resolve(dirname(outDir), '.smrt-planner-'));
+    try {
+        cpSync(source, temporary, { recursive: true });
+        patchFallback(resolve(temporary, '404.html'), basePath);
+        writeFileSync(resolve(temporary, 'planner.config.json'), `${JSON.stringify(config, null, 2)}\n`);
+        if (existsSync(outDir))
+            rmdirSync(outDir);
+        renameSync(temporary, outDir);
+    }
+    catch (error) {
+        rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+    return {
+        outDir,
+        configFile: resolve(outDir, 'planner.config.json'),
+        fallbackFile: resolve(outDir, '404.html'),
+    };
+}

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  *
  * @module
  */
-export { type ByoPresetDefinition, type ConfigResult, type InferenceConfig, type InferenceMode, loadInferenceConfig, parseInferenceConfig, } from './inference/config.ts';
+export { type ByoPresetDefinition, type ConfigResult, type CredentialPersistence, type InferenceConfig, type InferenceMode, loadInferenceConfig, parseInferenceConfig, } from './inference/config.ts';
 export { createHostChat, type HostChatOptions, type HostRequest, } from './inference/host.ts';
 export { createOpenAIChat, testConnection } from './inference/openai.ts';
 export { type KitchenConfig, type KitchenEndpoint, type KitchenOutcome, type KitchenResult, parseKitchenConfig, sendToKitchen, } from './kitchen/client.ts';

package/dist/inference/byo.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { ChatModel } from '../assistant/transport.ts';
-import type { ByoPresetDefinition } from './config.ts';
+import type { ByoPresetDefinition, CredentialPersistence } from './config.ts';
 import { type ConnectionResult } from './openai.ts';
 /** Choices (not the key): which endpoint, its address and model, and whether it is in use. */
 export declare const BYO_PREFS_KEY = "smrt-planner:inference:v1";
@@ -24,6 +24,8 @@ export declare function loadByoKeys(storage: Storage | null): Record<string, Byo
 export type ByoTestStatus = 'idle' | 'testing' | 'ok' | 'failed';
 export interface ByoOptions {
     storage: Storage | null;
+    /** Credentials default to local storage for compatibility; hosted apps use memory. */
+    credentialPersistence?: CredentialPersistence;
     /** The config's `byo.presets`; default all built-ins. */
     presets?: readonly (string | ByoPresetDefinition)[];
     fetch?: typeof fetch;
@@ -33,8 +35,9 @@ export interface ByoOptions {
 /**
  * The visitor's own OpenAI-compatible endpoint: the preset they picked, its
  * address, model and key, a connection test, and whether the assistant uses
- * it. The key lives only in this browser's localStorage and is only ever sent
- * as the Authorization header to the chosen address.
+ * it. The key lives in the configured credential store (tab memory for hosted
+ * policies, localStorage for the compatible standalone default) and is only
+ * ever sent as the Authorization header to the chosen address.
  */
 export declare class ByoModel {
     readonly presets: ByoPresetDefinition[];
@@ -45,6 +48,7 @@ export declare class ByoModel {
     testStatus: ByoTestStatus;
     testMessage: string;
     private readonly options;
+    private readonly credentialStorage;
     constructor(options: ByoOptions);
     get preset(): ByoPresetDefinition | undefined;
     get baseUrl(): string;
@@ -82,5 +86,5 @@ export declare class ByoModel {
  * (a mounted `Planner` in byo mode has no AI page of its own). Null when none
  * is connected or what was saved is incomplete.
  */
-export declare function savedByoChat(storage: Storage | null, presets?: readonly (string | ByoPresetDefinition)[], fetcher?: typeof fetch): ChatModel | null;
+export declare function savedByoChat(storage: Storage | null, presets?: readonly (string | ByoPresetDefinition)[], fetcher?: typeof fetch, credentialPersistence?: CredentialPersistence): ChatModel | null;
 export {};