dsh-quick-actions 0.1.0 → 0.2.0-rc.1

package/lib/types/host/index.d.ts

@@ -1,38 +1,35 @@
 import type { CanonicalRewriteOutcome, SettingsRewriteProvider } from './settings.js';
 import type { PresetCatalog } from '../model/index.js';
 /**
- * The read-only catalog projection published to Clients (spec 6.2, 17.2). It is
- * the catalog itself under the name the spec gives it — one shape, so the Host
- * cannot publish something the model never validated.
+ * The read-only catalog projection (spec 6.2). It is the catalog itself under
+ * the name the spec gives it — one shape, so the Host cannot publish something
+ * the model never validated.
  */
 export type CatalogSnapshot = PresetCatalog;
-/**
- * The Host settings provider as this plugin uses it: namespace registration plus
- * the fenced write face. Declared structurally so the Host is testable against a
- * controlled fake; the real `SettingsProvider` satisfies it.
- */
-export interface QuickActionsSettingsProvider extends SettingsRewriteProvider {
-    register(ns: string, schema: unknown, options?: unknown): unknown;
-}
+/** The Host settings provider as this plugin uses it; the real `SettingsForms` satisfies it. */
+export type QuickActionsSettingsProvider = SettingsRewriteProvider;
 /** The running Host, owned by the fiber that started it. */
 export interface QuickActionsHost {
-    /** Settles when the startup canonical rewrite has been attempted. */
-    readonly ready: Promise<CanonicalRewriteOutcome>;
     /**
-     * The read-only Remote payload (spec 6.2): lossless JSON, no Settings CRUD.
-     * Each call hands back a detached copy, so a consumer cannot reach the
-     * authoritative catalog through the value it was given.
+     * The authoritative catalog as lossless JSON. Each call hands back a detached
+     * copy, so a consumer cannot reach the authoritative catalog through the value
+     * it was given.
      */
     describeCatalog(): Promise<CatalogSnapshot>;
+    /**
+     * Canonicalize the stored section against this catalog (spec 6.3). Only
+     * meaningful once the entry is active: before that the provider does not
+     * serve the form, and the answer is `unregistered`.
+     */
+    canonicalize(settings: QuickActionsSettingsProvider): Promise<CanonicalRewriteOutcome>;
 }
 /**
- * Load the catalog, register both namespaces and canonicalize the stored section.
+ * Load and validate the catalog.
  *
- * An invalid preset configuration throws before anything is registered: the
- * catalog is author-owned, so a mistake fails plugin loading rather than
- * silently shipping a partial catalog (spec 5.1).
+ * An invalid preset configuration throws: the catalog is author-owned, so a
+ * mistake fails plugin loading rather than silently shipping a partial catalog
+ * (spec 5.1).
  *
- * @param settings - the Host settings provider.
  * @param config - the Host composition entry's config.
  */
-export declare function startQuickActionsHost(settings: QuickActionsSettingsProvider, config: unknown): QuickActionsHost;
+export declare function startQuickActionsHost(config: unknown): QuickActionsHost;

package/lib/types/host/settings.d.ts

@@ -1,67 +1,82 @@
 /**
- * The single persisted Settings namespace and the Host's canonical rewrite
- * (spec 4.2, 6.1, 6.3).
+ * The plugin's Config — which since DSH 0.1.7 *is* its Settings form — and the
+ * Host's canonical rewrite (spec 4.2, 6.1, 6.3, 22).
  *
- * The Host is the sole validation and migration authority, so the registered
- * schema is deliberately permissive: it fixes the shape of the section and its
- * defaults, and nothing else. A strict schema would refuse registration for a
- * section a higher version wrote — which is exactly the data spec 5.3 requires
- * to survive a downgrade untouched. The shared model decodes and normalizes what
- * the schema lets through, and it never rewrites content it cannot render.
+ * The Host is the sole validation and migration authority, so the schema is
+ * deliberately permissive: it fixes the shape of the section and its defaults,
+ * and nothing else. A strict schema would refuse a section a higher version
+ * wrote — which is exactly the data spec 5.3 requires to survive a downgrade
+ * untouched. The shared model decodes and normalizes what the schema lets
+ * through, and it never rewrites content it cannot render.
  */
 import Schema from '@deepseek-ai/schemastery';
 import type { PresetCatalog, QuickActionSettingsV1 } from '../model/index.js';
 /**
- * Shape and defaults of the persisted section (spec 4.2). The three collections
- * stay unconstrained on purpose: a stricter schema would refuse registration for
- * a section this release cannot render, and refusing registration is how stored
- * data gets lost. The shared model is the validation gate — see the module note.
- */
-export declare const quickActionSettingsSchema: Schema<Schemastery.ObjectS<{
-    schemaVersion: Schema<number, number>;
-    layout: Schema<string, string>;
-    userActionsById: Schema<any, any>;
-    actionOrder: Schema<any, any>;
-    presetStateById: Schema<any, any>;
-}>, Schemastery.ObjectT<{
-    schemaVersion: Schema<number, number>;
-    layout: Schema<string, string>;
-    userActionsById: Schema<any, any>;
-    actionOrder: Schema<any, any>;
-    presetStateById: Schema<any, any>;
-}>>;
-/**
- * Shape of the catalog namespace. Its authoritative content is the composition
- * `base` layer the Host declares; a user layer is never written and, if one were
- * hand-written into the document, Clients would still read `base` (spec 17.2).
+ * The plugin Config (spec 22.2). Every field is `volatile`, because DSH lets a
+ * Settings form — and so the Client — reach volatile fields only.
+ *
+ * - The five user-state fields are top-level on purpose: the DSH legacy import
+ *   moves an old `settings.yaml` section into the entry of the same id key by
+ *   key, and refuses the whole section when any top-level key is not a volatile
+ *   field. This exact shape is what lets that one-shot import land.
+ * - `presets` is the author's list merged behind the built-ins (spec 5.1). It
+ *   is volatile only so the Client can read it — a non-volatile field never
+ *   reaches the browser — and nothing in this plugin ever writes it.
+ *
+ * The collections stay unconstrained: a stricter schema would refuse a section
+ * this release cannot render, and refusing it is how stored data gets lost.
  */
-export declare const quickActionCatalogSchema: Schema<Schemastery.ObjectS<{
-    schemaVersion: Schema<number, number>;
-    revision: Schema<string, string>;
-    presets: Schema<any, any>;
-}>, Schemastery.ObjectT<{
-    schemaVersion: Schema<number, number>;
-    revision: Schema<string, string>;
-    presets: Schema<any, any>;
-}>>;
-/** One namespace as the provider describes it. */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    presets: Schema<any, any, "volatile-defined">;
+    schemaVersion: Schema<number, number, "volatile-defined">;
+    layout: Schema<string, string, "volatile-defined">;
+    userActionsById: Schema<any, any, "volatile-defined">;
+    actionOrder: Schema<any, any, "volatile-defined">;
+    presetStateById: Schema<any, any, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    presets: Schema<any, any, "volatile-defined">;
+    schemaVersion: Schema<number, number, "volatile-defined">;
+    layout: Schema<string, string, "volatile-defined">;
+    userActionsById: Schema<any, any, "volatile-defined">;
+    actionOrder: Schema<any, any, "volatile-defined">;
+    presetStateById: Schema<any, any, "volatile-defined">;
+}>>, "plain">;
+/** One path-addressed field write, as the settings provider takes it. */
+export interface SettingsSetOp {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+}
+/** One form as the provider describes it. */
 export interface SettingsDescriptorLike {
     readonly ns: string;
-    /** Monotonic revision of the raw user section; send it back to fence a write. */
+    /** Monotonic revision of the raw entry configuration; send it back to fence a write. */
     readonly revision: number;
-    /** The raw stored user section, absent while nothing was ever written. */
+    /** The form fields the active profile patch sets. */
     readonly user?: unknown;
 }
 /**
  * The part of the Host settings provider the canonical rewrite reads and writes
  * through. Declared structurally so the rewrite is testable against a controlled
- * fake — the real `SettingsProvider` satisfies it as-is.
+ * fake — the real `SettingsForms` satisfies it as-is.
  */
 export interface SettingsRewriteProvider {
     readonly writable: boolean;
     describe(): readonly SettingsDescriptorLike[];
-    replace(ns: string, section: object, expectedRevision?: number): Promise<void>;
+    mutate(ns: string, ops: readonly SettingsSetOp[], expectedRevision?: number): Promise<void>;
 }
+/**
+ * One write per user-state field, never touching `presets`: the author's list
+ * shares the entry's config, and a write that restated it would pin whatever it
+ * read into the profile layer.
+ */
+export declare function stateOps(section: QuickActionSettingsV1): readonly SettingsSetOp[];
+/**
+ * The user-state fields the profile layer actually sets, or `undefined` when it
+ * sets none. The same layer may carry the author's `presets`; those are Config,
+ * not stored state, so a profile holding only presets has nothing stored.
+ */
+export declare function storedState(user: unknown): Readonly<Record<string, unknown>> | undefined;
 export type CanonicalRewriteOutcome = 
 /** The stored section already was canonical; nothing was written. */
 {
@@ -90,7 +105,7 @@ export type CanonicalRewriteOutcome =
 } | {
     readonly status: 'read-only';
 }
-/** The namespace is not registered yet, so there is nothing to fence a write to. */
+/** The form is not served — the entry is not active — so there is nothing to fence a write to. */
  | {
     readonly status: 'unregistered';
 };
@@ -99,9 +114,9 @@ export type CanonicalRewriteOutcome =
  * persist it behind the revision it was read at (spec 6.3).
  *
  * Nothing is written when nothing is stored: materializing the defaults into the
- * user layer would shadow the composition `base` and destroy what `replace({})`
- * resets to. Nothing is written for a higher `schemaVersion` either — that data
- * belongs to the version that wrote it.
+ * profile layer would shadow every layer below it for good. Nothing is written
+ * for a higher `schemaVersion` either — that data belongs to the version that
+ * wrote it.
  *
  * A conflict means another writer won the race, so the rewrite refreshes the
  * authoritative snapshot and recomputes rather than replaying its own stale

package/lib/types/index.d.ts

@@ -1,31 +1,33 @@
 /**
  * Host composition entry for Composer Quick Actions.
  *
- * `settings` is a hard dependency: the concrete provider (`dsh-settings-file`)
- * *is* the service, so injecting it is how this plugin waits for the backend
- * instead of inventing an in-memory, browser or private-file store (spec 6.1).
- * A provider that is present but not writable is a supported state, not a
- * missing one — the stored section is left untouched and the surfaces go
- * read-only (spec 10).
+ * Since DSH 0.1.7 the stored section is this entry's own Config (spec 22): the
+ * exported `Config` declares it, the Loader hands it over, and DSH Settings
+ * reads and writes it through the active profile. There is no namespace to
+ * register and no second namespace for the catalog.
  *
- * Everything this entry registers — the Settings namespace and the startup
- * rewrite's reporting — is owned by this fiber and withdrawn when it unloads.
- * The user's stored section deliberately survives unload, so reinstalling
- * restores the user's actions.
+ * `settings` is therefore an optional dependency, as for every first-party
+ * plugin: the Quick Actions run without it, and while it is present this entry
+ * opts out of an auto-generated Settings page — the plugin ships its own
+ * management panel — and canonicalizes the stored section once every entry of
+ * the profile has settled.
+ *
+ * Everything this entry installs is owned by this fiber and withdrawn when it
+ * unloads. The user's stored section deliberately survives unload, so
+ * reinstalling restores the user's actions.
  *
  * The public surface is the plugin contract only. The shared model, the
  * Settings rewrite and the catalog assembly stay internal to the package
- * (spec 11.2); whether any of them becomes a published runtime export belongs
- * to the release-surface decision.
+ * (spec 11.2).
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { QuickActionsHost } from './host/index.js';
 export declare const name = "composer-quick-actions";
-export declare const inject: readonly string[];
+export { Config } from './host/settings.js';
 export type { ComposerQuickActionsConfig } from './host/config.js';
 export type { CatalogSnapshot, QuickActionsHost } from './host/index.js';
 /**
- * Load the Preset Catalog, register the Settings namespace and canonicalize the
+ * Load the Preset Catalog and, while Settings is present, canonicalize the
  * stored section. An invalid preset configuration throws here, failing plugin
  * loading loudly rather than shipping a partial catalog (spec 5.1).
  *

package/lib/types/model/catalog.d.ts

@@ -3,11 +3,11 @@ import type { PresetQuickAction, QuickActionField, QuickActionIssueReason } from
 export declare const QUICK_ACTION_CATALOG_LIMIT = 50;
 /** Where a catalog entry was declared. */
 export type PresetSource = 'builtin' | 'config';
-/** What the Host feeds the model: raw JSON, validated here rather than upstream. */
+/** What either face feeds the model: raw JSON, validated here rather than upstream. */
 export interface PresetCatalogInput {
     /** The package's built-in manifest, in declaration order. */
     readonly builtins: readonly unknown[];
-    /** `Config.presets` from the Host composition, in declaration order. */
+    /** The `presets` Config field, in declaration order. */
     readonly configured: readonly unknown[];
 }
 /** One reason the plugin config must fail to load. */
@@ -25,7 +25,7 @@ export type PresetCatalogIssue = {
     readonly count: number;
     readonly limit: number;
 };
-/** The authoritative, read-only catalog snapshot the Remote publishes (spec 6.2). */
+/** The authoritative, read-only Preset Catalog (spec 6.2): what the Host validates and the Client rebuilds (spec 22.3). */
 export interface PresetCatalog {
     readonly schemaVersion: 1;
     /** Determined by the catalog projection; any change to it changes this value. */
@@ -46,18 +46,3 @@ export type PresetCatalogResult = {
  * author got wrong, so the mistake surfaces at startup rather than at send time.
  */
 export declare function buildPresetCatalog(input: PresetCatalogInput): PresetCatalogResult;
-/**
- * Read one published catalog snapshot back (spec 17.2). The Host is the catalog's
- * single validation authority, so this is a defensive decode of an already
- * confirmed snapshot rather than a second authority — but it is a decode, not a
- * cast: a snapshot this release cannot read in full yields no catalog at all.
- *
- * All-or-nothing on purpose. Dropping the entries it cannot read would show the
- * user a silently truncated action list, which is exactly what spec 5.1 forbids
- * the Host to do; the consumer reports a catalog error instead (spec 10).
- *
- * The Host's `revision` is carried through rather than recomputed. It is the
- * catalog's published identity, and a Client that recomputed it would be
- * asserting an authority it does not have.
- */
-export declare function decodeCatalogSnapshot(raw: unknown): PresetCatalog | undefined;

package/lib/types/model/index.d.ts

@@ -7,6 +7,7 @@ export * from './json.js';
 export * from './text.js';
 export * from './validation.js';
 export * from './catalog.js';
+export * from './presets.js';
 export * from './settings.js';
 export * from './normalize.js';
 export * from './projection.js';

package/lib/types/{host → model}/presets.d.ts

@@ -3,6 +3,11 @@
  * Preset Catalog (spec 5.1), declared ahead of the Host composition's
  * `Config.presets`.
  *
+ * It lives in the shared model because both faces merge it: the Host validates
+ * the catalog at load, and the Client rebuilds the same catalog from this list
+ * plus the `presets` form field it reads (spec 22.3). One list, so the two can
+ * never disagree about what the built-ins are.
+ *
  * These are author-facing product copy in one language; changing a label or a
  * text is a product decision, not an implementation one.
  *

package/lib/types/model/settings.d.ts

@@ -1,16 +1,20 @@
 import type { CustomQuickActionValue, PresetQuickActionState, QuickActionSettingsV1, QuickActionTombstone, StoredQuickActionValue } from './types.js';
 /**
- * The one namespace holding user data (spec 4.2); renaming it orphans every
- * stored section. It lives in the shared model because both faces address it:
- * the Host registers it, the Client binds the same name.
+ * The one namespace holding user data (spec 4.2, 22); renaming it orphans every
+ * stored section. Since DSH 0.1.7 a Settings namespace *is* a profile entry id,
+ * so this is also the Cordis loader entry id the bundle patch inserts — the two
+ * can no longer drift apart. It lives in the shared model because both faces
+ * address it: the Host describes and fences its canonical rewrite against it,
+ * the Client reads and writes the same form.
  */
 export declare const QUICK_ACTIONS_SETTINGS_NAMESPACE = "composer-quick-actions";
 /**
- * The read-only namespace carrying the Preset Catalog to Clients (spec 17.2).
- * The plugin never writes its user layer, so it holds no persisted section —
- * `composer-quick-actions` remains the only persisted namespace (spec 4.2).
+ * The top-level fields of the stored section, in canonical order (spec 4.2).
+ * Each is a separate volatile Config field (spec 22.2): the DSH legacy import
+ * addresses a section by these exact top-level keys, and every write sets them
+ * field by field so a write never reaches the author's `presets`.
  */
-export declare const QUICK_ACTIONS_CATALOG_NAMESPACE = "composer-quick-actions-catalog";
+export declare const QUICK_ACTION_STATE_FIELDS: readonly ["schemaVersion", "layout", "userActionsById", "actionOrder", "presetStateById"];
 /** The state a fresh install starts from (spec 4.2). */
 export declare const DEFAULT_QUICK_ACTION_SETTINGS: QuickActionSettingsV1;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-quick-actions",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.1",
   "description": "Persistent Quick Actions for the DSH message composer",
   "license": "MIT",
   "repository": {
@@ -60,23 +60,28 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-connection": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.5-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-settings": ">=0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-client-connection": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.7-rc.1",
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "@types/react": "~18.3.31",
     "@types/react-dom": "~18.3.7",
     "react": "^18.3.1",