@huanlin/dsh-plugin-aigc-canvas 0.1.10 → 0.2.1

package/lib/provider-shape.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure provider-id validation shared by the host half (Config / ProviderStore)
+ * and the client settings page. Kept free of schemastery imports so the
+ * client bundle (tsdown purity gate) can inline it.
+ *
+ * @module @huanlin/dsh-plugin-aigc-canvas/provider-shape
+ */
+/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
+export declare const PROVIDER_ID_PATTERN: RegExp;
+/**
+ * Validate a provider id.
+ * @param id - candidate id (as typed into the settings page or passed to the store).
+ * @returns an error message, or undefined when valid.
+ */
+export declare function validateProviderId(id: string): string | undefined;

package/lib/provider-store.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Provider store with CRUD, read-through the entry's profile-owned Cordis
+ * Config when a persistence face is attached (the list persists in the
+ * active profile's `cordis.patch.yml` under the `dsh-aigc-canvas` entry id,
+ * dsh 0.1.7-rc.1 DSH-0.1.7-J1-04). Reads derive from the persistence
+ * source on every call, so edits committed by ANY writer (the settings
+ * page through the client `configForms` transport, the model's
+ * aigc_provider_set_instructions tool, a hand-edited profile patch) are
+ * visible immediately. Without an attached face (headless assemblies with
+ * no settings provider) the store is in-memory only: composition seed,
+ * lost on unload.
+ *
+ * @module @huanlin/dsh-plugin-aigc-canvas/provider-store
+ */
 import type { AigcProvider, ResolvedAigcProvider } from './config.js';
 /** CRUD result: the success branch carries the latest list. */
 export type ProviderMutationResult = {
@@ -8,43 +22,64 @@ export type ProviderMutationResult = {
     readonly error: string;
 };
 /**
- * Mutable provider store. Owns the canonical provider list; the backend
- * client map and RPC handlers share one instance per plugin fiber.
+ * Persistence face attached to a {@link ProviderStore}.
  *
- * Persistence: on construction the store loads `~/.dsh/aigc-canvas/
- * providers.json` (if present) and merges it over the cordis.yml seed —
- * persisted providers win, so user edits and deletions survive restarts.
- * Every mutation writes the list back to disk (fire-and-forget).
+ * `source` reads the currently committed raw list (the entry's live volatile
+ * config); `persist` commits a replacement. Both are provided by
+ * `installAigcSettings` (see `settings.ts`).
+ */
+export interface ProviderPersistence {
+    /** The currently committed raw provider list. */
+    source(): readonly AigcProvider[];
+    /** Commit a replacement list. */
+    persist(providers: readonly AigcProvider[]): Promise<void>;
+}
+/**
+ * Mutable provider store. Owns the canonical provider list; tool
+ * registration shares one instance per plugin fiber.
+ *
+ * While no persistence face is attached the in-memory map is canonical
+ * (headless mode). Once a face is attached, every read resolves through the
+ * face's source and every mutation commits through `persist` before its
+ * result is reported — the committed profile config is the single source of
+ * truth.
  */
 export declare class ProviderStore {
     private readonly providers;
-    private readonly dataPath;
-    /** Serializes disk writes so rapid mutations can't interleave. */
-    private persistChain;
-    constructor(seed: readonly AigcProvider[], dataPath?: string);
-    /** Snapshot of all providers, in insertion order. */
+    /** Optional persistence face; absent in headless mode. */
+    private persistence;
+    /** @param seed - resolved seed providers (the composition layer). */
+    constructor(seed: readonly ResolvedAigcProvider[]);
+    /**
+     * Attach a persistence face. Subsequent reads derive from the face's
+     * source and mutations commit through it.
+     * @param persistence - the read/write face over the entry's config.
+     */
+    attachPersistence(persistence: ProviderPersistence): void;
+    /** The committed provider list (insertion order; duplicates keep the first). */
+    private committed;
+    /** Snapshot of all providers, in order. */
     list(): readonly ResolvedAigcProvider[];
     /** Look up one provider by id. */
     get(id: string): ResolvedAigcProvider | undefined;
-    /** The default provider (first in insertion order); undefined if empty. */
+    /** The default provider (first in order); undefined if empty. */
     defaultProvider(): ResolvedAigcProvider | undefined;
     /** Add a new provider. Returns failure for duplicate id or invalid shape. */
-    add(provider: AigcProvider): ProviderMutationResult;
+    add(provider: AigcProvider): Promise<ProviderMutationResult>;
     /** Update an existing provider. Returns failure if the id is unknown. */
-    update(provider: AigcProvider): ProviderMutationResult;
+    update(provider: AigcProvider): Promise<ProviderMutationResult>;
     /**
      * Replace a provider's usage instructions (called by the model's
      * aigc_provider_set_instructions tool after it probes the API).
      */
-    setInstructions(id: string, instructions: string): ProviderMutationResult;
+    setInstructions(id: string, instructions: string): Promise<ProviderMutationResult>;
     /** Remove a provider. Returns failure for unknown id. */
-    remove(id: string): ProviderMutationResult;
+    remove(id: string): Promise<ProviderMutationResult>;
     /**
-     * Persist the current provider list to disk (fire-and-forget, serialized).
-     * Only the user-editable fields are written; `builtin` is re-derived from
-     * the seed on load. Failures are swallowed — the in-memory state stays
-     * canonical. Each call snapshots the CURRENT list, so a burst of mutations
-     * ends with the latest state on disk.
+     * Commit a replacement list: through the persistence face when attached
+     * (the post-commit committed value is reported), otherwise into the
+     * in-memory map. A refused persistence write leaves the committed state
+     * untouched and reports `{ ok: false }`.
      */
-    private persist;
+    private commit;
 }

package/lib/settings.d.ts

@@ -0,0 +1,78 @@
+/**
+ * settings.ts — host-side bridge between the entry's profile-owned Config
+ * and the plugin's provider store, plus the one-time legacy import.
+ *
+ * dsh 0.1.7-rc.1 (`DSH-0.1.7-J1-04`) removed the namespace-registration API:
+ * a plugin declares a Cordis `Config` (see `config.ts`, `providers` marked
+ * `.volatile()`) and only declares the presentation policy for its own page.
+ * The bridge exposes:
+ *
+ *   - `source()`: the raw committed provider list, read from the live
+ *     volatile reference on every call, so the tools and RPC surface always
+ *     serve the latest accepted value (including edits written by other
+ *     surfaces through the settings service).
+ *   - `persist(providers)`: commits a replacement list through the settings
+ *     service, which writes it into the active profile's `cordis.patch.yml`
+ *     under the entry id `dsh-aigc-canvas` and updates the live reference
+ *     in place.
+ *   - `writable`: whether a settings provider is mounted.
+ *
+ * On first mount the legacy persistence file of pre-0.1.11 versions
+ * (`~/.dsh/aigc-canvas/providers.json`) is imported once (the file is
+ * renamed before the import, so a partial import never repeats) and left
+ * behind as `providers.json.imported`.
+ *
+ * @module @huanlin/dsh-plugin-aigc-canvas/settings
+ */
+import type { AigcEntryConfig, AigcProvider } from './config.js';
+import type { AigcSettingsForms, Context } from './context-types.js';
+/** Profile entry id under which the provider list persists (`cordis.patch.yml`). */
+export declare const SETTINGS_NAMESPACE = "dsh-aigc-canvas";
+/** Default legacy persistence path (pre-0.1.11 custom file). */
+export declare const LEGACY_PROVIDERS_JSON: string;
+/** Minimal logger face (cordis `ctx.logger`). */
+interface AigcLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+/** Read/write face the provider store consumes. */
+export interface AigcSettingsBridge {
+    /** The raw committed provider list, read from the entry's live volatile config. */
+    source(): readonly AigcProvider[];
+    /**
+     * Commit a replacement provider list to the profile entry config.
+     * No-op without a mounted settings provider (headless assemblies).
+     */
+    persist(providers: readonly AigcProvider[]): Promise<void>;
+    /** Whether a settings provider is mounted (false in headless assemblies). */
+    readonly writable: boolean;
+}
+/**
+ * Declare the plugin's settings presentation policy and return the bridge.
+ *
+ * `auto: false` suppresses the schema-generated page: this plugin ships its
+ * own editor as the bundle row's `plugins.row.config` entry on the Plugins
+ * page.
+ *
+ * @param ctx - host context.
+ * @param entry - the entry's volatile Cordis config.
+ * @param options - optional overrides (legacy import path, attach callback).
+ * @param options.legacyPath - path of the legacy providers file to import once.
+ * @param options.onReady - invoked when the settings provider is mounted (before the legacy import settles).
+ * @returns the bridge the provider store consumes.
+ */
+export declare function installAigcSettings(ctx: Context, entry: AigcEntryConfig | undefined, options?: {
+    legacyPath?: string;
+    onReady?: () => void;
+}): AigcSettingsBridge;
+/**
+ * Import the legacy `providers.json` once: rename the file first (so a
+ * partial import never repeats), then commit the parsed list into the
+ * profile entry config. Failures are logged, never thrown.
+ *
+ * @param path - the legacy file path.
+ * @param settings - the mounted settings service.
+ * @param logger - the host logger.
+ */
+export declare function importLegacyProviders(path: string, settings: AigcSettingsForms, logger: AigcLogger): Promise<void>;
+export {};

package/lib/tools.d.ts

@@ -31,7 +31,7 @@ export interface ProviderInfo {
  *
  * @param ctx - host plugin context (carries the tools service).
  * @param getProvider - live provider getter (takes optional provider id).
- * @param setInstructions - persists usage instructions for one provider (the host's ProviderStore).
+ * @param setInstructions - persists usage instructions for one provider (the host's ProviderStore; resolves after the profile-config commit).
  * @param listProviders - returns info for all providers (for aigc_get_provider_info).
  * @param canvas - the canvas registry service (host-owned state).
  * @param resolveCwd - live cwd resolver for one session id.
@@ -39,9 +39,9 @@ export interface ProviderInfo {
  * @param getMediaLimit - live cap on bytes the http tool may write to disk.
  * @returns a disposer that unregisters all tools.
  */
-export declare function registerTools(ctx: Context, getProvider: (providerId?: string) => ResolvedAigcProvider, setInstructions: (id: string, instructions: string) => {
+export declare function registerTools(ctx: Context, getProvider: (providerId?: string) => ResolvedAigcProvider, setInstructions: (id: string, instructions: string) => Promise<{
     ok: boolean;
     error?: string;
-}, listProviders: () => readonly ProviderInfo[], canvas: AigcCanvasService, resolveCwd: (sessionId: string) => string, getTimeoutMs: () => number, getMediaLimit?: () => number): () => void;
+}>, listProviders: () => readonly ProviderInfo[], canvas: AigcCanvasService, resolveCwd: (sessionId: string) => string, getTimeoutMs: () => number, getMediaLimit?: () => number): () => void;
 /** Re-export the projection helpers for the unit tests. */
 export { elementProjection, edgeProjection, titleOf };

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "AIGC Canvas",
+    "description": "An infinite free canvas for better-sidebar plus provider-agnostic generation: the agent calls any configured provider via aigc_http_request (endpoint + apiKey attached automatically) and places generated images, videos, and audio at arbitrary canvas positions; double-click an element to inspect its prompt and params."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "AIGC 画布",
+    "description": "面向 better-sidebar 的无限自由画布,搭配供应商无关的生成:模型通过 aigc_http_request 调用任意已配置供应商(endpoint + apiKey 自动附加),生成的图片/视频/音频可放置在画布任意位置,双击元素即可查看提示词与生成参数。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huanlin/dsh-plugin-aigc-canvas",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -22,6 +22,7 @@
       "types": "./lib/types/client/service.d.ts",
       "default": "./lib/client.js"
     },
+    "./locale/*.json": "./locale/*.json",
     "./package.json": "./package.json"
   },
   "engines": {
@@ -30,6 +31,7 @@
   "files": [
     "lib/",
     "assets/",
+    "locale/",
     "cordis.patch.yml"
   ],
   "dsh": {
@@ -43,6 +45,7 @@
         "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
         "@deepseek-ai/dsh-client-ui-primitives"
       ],
       "platform": "web"
@@ -54,15 +57,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
     "cordis": "^4.0.0-rc.7",
     "dsh-better-sidebar": "^0.4.0",
     "react": "^18.2.0",
@@ -81,6 +85,9 @@
     "@deepseek-ai/dsh-client-ui-settings": {
       "optional": true
     },
+    "@deepseek-ai/dsh-client-ui-plugin-manager": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-client-ui-conversation": {
       "optional": true
     },
@@ -117,6 +124,7 @@
     "@deepseek-ai/dsh-client-locale": "link:D:/Projects/deepseek-harness/dsh/packages/client/locale",
     "@deepseek-ai/dsh-client-ui-primitives": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-primitives",
     "@deepseek-ai/dsh-client-ui-settings": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-settings",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-plugin-manager",
     "@deepseek-ai/dsh-client-ui-conversation": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-conversation",
     "@deepseek-ai/dsh-client-ui-renderer": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-renderer",
     "@deepseek-ai/dsh-client-ui-slots": "link:D:/Projects/deepseek-harness/dsh/packages/client/ui-slots",