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

package/lib/config.d.ts

@@ -1,14 +1,17 @@
 /**
  * Serializable configuration and defaults for the AIGC canvas host half.
  * The `providers` array holds one or more AIGC provider configs (name /
- * endpoint / apiKey / instructions), editable at runtime through the DSH
- * GUI settings page; cordis.yml `config:` is the first-boot seed only.
+ * endpoint / apiKey / instructions). Since dsh 0.1.7-rc.1 the editable
+ * fields are `.volatile()` members of the entry's profile-owned Cordis
+ * Config (DSH-0.1.7-J1-04): the composition `config:` in cordis.patch.yml is
+ * the first-boot seed only, and runtime edits persist per profile under the
+ * entry id `dsh-aigc-canvas` through the settings service.
  *
  * @module @huanlin/dsh-plugin-aigc-canvas/config
  */
 import z from '@deepseek-ai/schemastery';
-/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
-export declare const PROVIDER_ID_PATTERN: RegExp;
+import type { Volatile } from '@deepseek-ai/cordis';
+export { PROVIDER_ID_PATTERN, validateProviderId } from './provider-shape.js';
 /** How the aigc_http_request tool attaches the provider apiKey to requests. */
 export interface AigcProviderAuth {
     /**
@@ -34,7 +37,7 @@ export interface AigcProvider {
     name: string;
     /** Provider API endpoint URL. `stub://aigc-backend` = the built-in stub. */
     endpoint: string;
-    /** Provider API key (stored in memory only; set via GUI or cordis.yml). */
+    /** Provider API key (persisted with the entry config in cordis.patch.yml; set via GUI or seed). */
     apiKey: string;
     /** Free-form usage instructions the agent reads via aigc_get_provider_info. */
     instructions: string;
@@ -52,8 +55,29 @@ export interface AigcCanvasConfig {
     /** Maximum media bytes to write to disk per generated asset. */
     mediaSizeLimit?: number;
 }
-/** Schemastery schema for the plugin configuration. */
-export declare const Config: z<AigcCanvasConfig>;
+/**
+ * The live Cordis config the Loader passes to `apply`.
+ *
+ * `providers` is `.volatile()`: the field arrives as a stable reference whose
+ * `.get()` always returns the latest accepted value (a committed settings
+ * edit updates it in place without remounting the plugin). The other fields
+ * are composition-seed knobs resolved once at load.
+ */
+export interface AigcEntryConfig {
+    /** Live provider list reference; `.get()` returns the latest accepted value. */
+    providers?: Volatile<readonly AigcProvider[]>;
+    requestTimeoutMs?: number;
+    mediaSizeLimit?: number;
+}
+/**
+ * Schemastery schema for the plugin's profile-owned Config.
+ *
+ * `providers` is `.volatile()` (dsh 0.1.7-rc.1 DSH-0.1.7-J1-04): the settings
+ * service enumerates the entry's volatile fields for the configuration form,
+ * and a committed edit updates the running reference in place. The numeric
+ * knobs stay non-volatile (cordis.patch.yml seed only).
+ */
+export declare const Config: z<AigcEntryConfig>;
 /** A fully-resolved provider (all fields guaranteed). */
 export interface ResolvedAigcProvider extends AigcProvider {
     name: string;
@@ -71,7 +95,21 @@ export interface ResolvedAigcConfig {
 }
 /** Returns true when the provider endpoint points at the built-in stub backend. */
 export declare function isStubEndpoint(endpoint: string): boolean;
-/** Validate a provider id; returns an error message or undefined if valid. */
-export declare function validateProviderId(id: string): string | undefined;
-/** Apply direct-call defaults after Loader schema validation has normally run. */
-export declare function resolveAigcConfig(config: AigcCanvasConfig | undefined): ResolvedAigcConfig;
+/**
+ * Normalize a raw provider list (the volatile reference's latest snapshot, a
+ * legacy imported document, or a hand-edited override) into resolved
+ * providers. Non-object entries are skipped; duplicate ids keep the first
+ * occurrence (insertion order preserved).
+ * @param raw - the raw list value.
+ * @returns the resolved providers, in order, deduplicated by id.
+ */
+export declare function resolveAigcProviders(raw: unknown): readonly ResolvedAigcProvider[];
+/**
+ * Resolve the apply-time seed config (direct-call defaults after Loader
+ * schema validation has normally run). The provider list reads the live
+ * volatile reference; when it resolves empty at load, the default stub is
+ * seeded so the tools always have one provider.
+ * @param config - the entry config the Loader passed to `apply`.
+ * @returns the fully defaulted seed settings.
+ */
+export declare function resolveAigcConfig(config: AigcEntryConfig | undefined): ResolvedAigcConfig;

package/lib/context-types.d.ts

@@ -84,6 +84,28 @@ export interface AigcLoaderEntry {
 export interface AigcLoader {
     entries(): Iterable<AigcLoaderEntry>;
 }
+/**
+ * The settings service face this plugin uses (mirror of
+ * `@deepseek-ai/dsh-settings` `SettingsForms`, dsh 0.1.7-rc.1). Restated
+ * structurally like the other faces above so the third-party resolution
+ * tree typechecks without a dependency on the DSH package.
+ */
+export interface AigcSettingsForms {
+    /** Register the calling plugin instance's settings-page policy. */
+    configure(presentation: {
+        auto?: boolean;
+    }, owner?: AigcCordisFiber): () => void;
+    /** Merge editable (volatile) fields into one entry's profile config. */
+    update(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+}
+/**
+ * Structural slice of the DSH-vendored cordis `Fiber`: `configure` keys its
+ * presentation policy by fiber identity, and the plugin only ever passes
+ * `ctx.fiber` through.
+ */
+export interface AigcCordisFiber {
+    readonly uid: number | null;
+}
 /**
  * The tools service face restated.
  * Mirrored here exactly like better-sidebar does — the dual-cordis-instance
@@ -101,6 +123,10 @@ declare module 'cordis' {
         sessions: AigcSessionStore;
         agents: AigcAgentRegistry;
         loader: AigcLoader;
+        /** The profile-owned settings forms service (dsh 0.1.7-rc.1); undefined when no settings provider is mounted. */
+        settings: AigcSettingsForms;
+        /** The plugin instance's fiber (DSH-vendored cordis). */
+        fiber: AigcCordisFiber;
         /**
          * The host-side AIGC canvas registry: holds the per-session element
          * table (prompts + generated assets) and edges. Provided by the host

package/lib/entry-identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * entry-identity.ts — the identity triple that binds this plugin's three
+ * naming surfaces together. Keeping them in one dependency-free module lets
+ * a unit test pin them against `cordis.patch.yml` and `package.json`
+ * (a mismatched `plugins.row.config` key fails silently: the row's configure
+ * entry simply never appears).
+ *
+ *  - ENTRY_ID: the profile entry id — the `id` of the insert row in
+ *    `cordis.patch.yml`. The Host serves the entry's volatile config under
+ *    it, so it keys `ctx.configForms.get` and `settings.update`.
+ *  - PACKAGE_NAME: the bundle's npm package name — the row's `name` field.
+ *  - ROW_CONFIG_KEY: the Plugins page `plugins.row.config` slot key,
+ *    `<package name>#<row id>` with the row id passed through verbatim.
+ *
+ * @module @huanlin/dsh-plugin-aigc-canvas/entry-identity
+ */
+/** Profile entry id (= the `cordis.patch.yml` insert row id / settings namespace). */
+export declare const ENTRY_ID = "dsh-aigc-canvas";
+/** Bundle package name (the Loader resolves the row's module through it). */
+export declare const PACKAGE_NAME = "@huanlin/dsh-plugin-aigc-canvas";
+/** `plugins.row.config` key: the bundle's package name `#` the patch row id. */
+export declare const ROW_CONFIG_KEY = "@huanlin/dsh-plugin-aigc-canvas#dsh-aigc-canvas";

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 import type { Context } from './context-types.js';
-import { Config, type AigcCanvasConfig, type AigcProvider, type ResolvedAigcConfig, type ResolvedAigcProvider } from './config.js';
-export { Config };
-export type { AigcCanvasConfig, AigcProvider, ResolvedAigcConfig, ResolvedAigcProvider };
+import { Config, type AigcEntryConfig, type AigcProvider, type ResolvedAigcConfig, type ResolvedAigcProvider } from './config.js';
+import { SETTINGS_NAMESPACE } from './settings.js';
+export { Config, SETTINGS_NAMESPACE };
+export type { AigcCanvasConfig } from './config.js';
+export type { AigcEntryConfig, AigcProvider, ResolvedAigcConfig, ResolvedAigcProvider };
 export type { Context } from './context-types.js';
 export type { AigcCanvasService, AigcElement, AigcEdge, AigcCanvasState, AigcElementKind, } from './canvas-registry.js';
 /** Plugin identity for cordis.yml rows. */
@@ -9,4 +11,4 @@ export declare const name = "dsh-aigc-canvas";
 /** Services required before mounting. */
 export declare const inject: string[];
 /** Plugin body. */
-export declare function apply(ctx: Context, config?: AigcCanvasConfig): void;
+export declare function apply(ctx: Context, config?: AigcEntryConfig): void;