dsh-quick-actions 0.1.0-rc.3

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

@@ -0,0 +1,113 @@
+/**
+ * The single persisted Settings namespace and the Host's canonical rewrite
+ * (spec 4.2, 6.1, 6.3).
+ *
+ * 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.
+ */
+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).
+ */
+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 interface SettingsDescriptorLike {
+    readonly ns: string;
+    /** Monotonic revision of the raw user section; send it back to fence a write. */
+    readonly revision: number;
+    /** The raw stored user section, absent while nothing was ever written. */
+    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.
+ */
+export interface SettingsRewriteProvider {
+    readonly writable: boolean;
+    describe(): readonly SettingsDescriptorLike[];
+    replace(ns: string, section: object, expectedRevision?: number): Promise<void>;
+}
+export type CanonicalRewriteOutcome = 
+/** The stored section already was canonical; nothing was written. */
+{
+    readonly status: 'unchanged';
+}
+/** Nothing is stored yet, so there is no stored state to canonicalize. */
+ | {
+    readonly status: 'nothing-stored';
+}
+/**
+ * The stored section belongs to a higher `schemaVersion`. This release reads it
+ * losslessly but must not write it back, or a downgrade would stamp its own
+ * version over data it does not own (spec 5.3, 16.1).
+ */
+ | {
+    readonly status: 'newer-version';
+    readonly schemaVersion: number;
+} | {
+    readonly status: 'rewritten';
+    readonly revision: number;
+}
+/** The namespace kept moving; the rewrite refused to overwrite the writer that won. */
+ | {
+    readonly status: 'conflict';
+    readonly attempts: number;
+} | {
+    readonly status: 'read-only';
+}
+/** The namespace is not registered yet, so there is nothing to fence a write to. */
+ | {
+    readonly status: 'unregistered';
+};
+/**
+ * Read the stored section, canonicalize it against the current catalog, and
+ * 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.
+ *
+ * A conflict means another writer won the race, so the rewrite refreshes the
+ * authoritative snapshot and recomputes rather than replaying its own stale
+ * section; after a bounded number of attempts it reports the conflict instead of
+ * overwriting the concurrent write.
+ */
+export declare function rewriteCanonicalSettings(settings: SettingsRewriteProvider, catalog: PresetCatalog): Promise<CanonicalRewriteOutcome>;
+/** Decode one raw stored section and canonicalize it against the catalog. */
+export declare function canonicalSettings(stored: unknown, catalog: PresetCatalog): QuickActionSettingsV1;

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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 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
+ * stored section. An invalid preset configuration throws here, failing plugin
+ * loading loudly rather than shipping a partial catalog (spec 5.1).
+ *
+ * @returns the running Host, so a composition that embeds this plugin directly
+ * can reach the catalog projection; the cordis loader ignores the value.
+ */
+export declare function apply(ctx: Context, config?: unknown): QuickActionsHost;

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

@@ -0,0 +1,34 @@
+/**
+ * Composer Quick Actions dictionaries (spec 8.4).
+ *
+ * Both shipped languages carry the same key set, so a missing translation is a
+ * compile error rather than a key leaking onto a surface. Keys are registered
+ * under one namespace and reached through the `t` prop the Slot registration's
+ * `locale` option binds; nothing here formats a date, a number or a plural.
+ *
+ * Two families of key are addressed by composition rather than by name — a
+ * field issue (`issue.<field>.<reason>`) and a write failure (`write.<kind>`) —
+ * because the model and the controller name those cases, not this file. Both go
+ * through {@link quickActionsLocaleKey}, which checks the composed key against
+ * the dictionary itself, so a case this release cannot phrase falls back to a
+ * general sentence instead of printing a raw key at the user.
+ */
+import type { QuickActionFieldIssue } from '../model/index.js';
+/** The locale namespace this package registers and every Slot entry binds. */
+export declare const QUICK_ACTIONS_LOCALE_NAMESPACE = "composer-quick-actions";
+/** Every key the Composer surfaces and the management panel render. */
+export type QuickActionsLocaleKey = 'title' | 'manage' | 'manage.tooltip' | 'more' | 'launcher' | 'empty' | 'command.badge' | 'unavailable.occupied-draft' | 'unavailable.composer-busy' | 'unavailable.composer-blocked' | 'unavailable.session-removed' | 'unavailable.parent-offline' | 'unavailable.sending' | 'feedback.state-changed' | 'feedback.retained' | 'feedback.failed' | 'feedback.dismiss' | 'catalog.loading' | 'catalog.unreadable' | 'catalog.unavailable' | 'catalog.undecodable' | 'catalog.retry' | 'crash.title' | 'crash.retry' | 'confirm.title' | 'confirm.send' | 'confirm.cancel' | 'confirm.command' | 'panel.title' | 'panel.close' | 'panel.search' | 'panel.search.empty' | 'manager.title' | 'manager.close' | 'manager.layout' | 'manager.layout.ribbon' | 'manager.layout.bar' | 'manager.layout.launcher' | 'manager.actions' | 'manager.count' | 'manager.new' | 'manager.empty' | 'manager.overflow' | 'manager.limit' | 'manager.command.notice' | 'manager.preset' | 'manager.custom' | 'manager.clonedFrom' | 'manager.hidden' | 'manager.disabled' | 'manager.hide' | 'manager.restore' | 'manager.clone' | 'manager.edit' | 'manager.enable' | 'manager.disable' | 'manager.delete' | 'manager.delete.confirm' | 'manager.delete.cancel' | 'manager.moveUp' | 'manager.moveDown' | 'manager.readonly.storage' | 'manager.readonly.offline' | 'form.title.new' | 'form.title.edit' | 'form.label' | 'form.label.hint' | 'form.text' | 'form.text.hint' | 'form.icon' | 'form.icon.hint' | 'form.confirm' | 'form.save' | 'form.cancel' | 'form.command.warning' | 'issue.invalid' | 'issue.label.blank' | 'issue.label.too-long' | 'issue.text.blank' | 'issue.text.too-long' | 'issue.text.reserved-placeholder' | 'issue.icon.not-emoji' | 'issue.icon.too-long' | 'write.dismiss' | 'write.retry' | 'write.not-ready' | 'write.read-only' | 'write.refused' | 'write.conflict' | 'write.failed' | 'write.invalid-fields' | 'write.limit-reached' | 'write.unknown-action' | 'write.id-in-use' | 'write.invalid-order';
+export type QuickActionsDictionary = Record<QuickActionsLocaleKey, string>;
+export declare const zh: QuickActionsDictionary;
+export declare const en: QuickActionsDictionary;
+/** The dictionaries as `ctx.locale.register` takes them. */
+export declare const quickActionsDictionaries: Record<string, QuickActionsDictionary>;
+/**
+ * Narrow a composed key to one this package ships, falling back when it does
+ * not. Composed keys come from names the model and the controller own — a field
+ * issue, a mutation refusal, a write failure — so a case added upstream shows a
+ * general sentence instead of leaking `write.something-new` onto a surface.
+ */
+export declare function quickActionsLocaleKey(candidate: string, fallback: QuickActionsLocaleKey): QuickActionsLocaleKey;
+/** The dictionary entry naming one field issue (spec 4.3). */
+export declare function quickActionIssueKey(issue: QuickActionFieldIssue): QuickActionsLocaleKey;

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

@@ -0,0 +1,63 @@
+import type { PresetQuickAction, QuickActionField, QuickActionIssueReason } from './types.js';
+/** Absolute threshold on the merged catalog itself (spec 5.4). */
+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. */
+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. */
+    readonly configured: readonly unknown[];
+}
+/** One reason the plugin config must fail to load. */
+export type PresetCatalogIssue = {
+    readonly scope: 'preset';
+    readonly source: PresetSource;
+    readonly index: number;
+    /** The declared id when it is a usable string, otherwise `undefined`. */
+    readonly id: string | undefined;
+    readonly field: QuickActionField;
+    readonly reason: QuickActionIssueReason;
+} | {
+    readonly scope: 'catalog';
+    readonly reason: 'too-many';
+    readonly count: number;
+    readonly limit: number;
+};
+/** The authoritative, read-only catalog snapshot the Remote publishes (spec 6.2). */
+export interface PresetCatalog {
+    readonly schemaVersion: 1;
+    /** Determined by the catalog projection; any change to it changes this value. */
+    readonly revision: string;
+    readonly presets: readonly PresetQuickAction[];
+}
+/** Either the authoritative catalog, or every reason config loading has to fail. */
+export type PresetCatalogResult = {
+    readonly ok: true;
+    readonly catalog: PresetCatalog;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PresetCatalogIssue[];
+};
+/**
+ * Merge and validate the built-in manifest with the Host composition's presets.
+ * Nothing is repaired or dropped: the first release refuses to load a catalog an
+ * 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

@@ -0,0 +1,13 @@
+/**
+ * Shared Quick Action domain model: pure JSON in, pure JSON out.
+ * Host and Client both consume it; it never touches cordis, React, the DOM or storage.
+ */
+export * from './types.js';
+export * from './json.js';
+export * from './text.js';
+export * from './validation.js';
+export * from './catalog.js';
+export * from './settings.js';
+export * from './normalize.js';
+export * from './projection.js';
+export * from './mutations.js';

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

@@ -0,0 +1,11 @@
+/**
+ * JSON structural comparison shared by the mutation planner and the Host's
+ * canonical rewrite.
+ *
+ * Structural, not canonical-JSON: object key order carries no meaning here.
+ * A stored section round-tripped through YAML, and a tombstone written by a
+ * higher version, both come back with whatever key order their writer chose —
+ * comparing serialized text would report a difference that is not one, and the
+ * rewrite would then write on every start instead of being idempotent.
+ */
+export declare function deepEqualJson(left: unknown, right: unknown): boolean;

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

@@ -0,0 +1,98 @@
+import type { PresetCatalog } from './catalog.js';
+import type { QuickActionDraft } from './validation.js';
+import type { CustomActionId, PresetActionId, QuickActionFieldIssue, QuickActionLayout, QuickActionRef, QuickActionSettingsV1 } from './types.js';
+/** What every planner reads: the confirmed snapshot, the catalog it was read against, and its revision. */
+export interface QuickActionMutationContext {
+    readonly settings: QuickActionSettingsV1;
+    readonly catalog: PresetCatalog;
+    /** The Settings namespace revision the resulting write must carry (spec 6.3). */
+    readonly revision: string;
+}
+/** What to persist, and the fence the write must carry. */
+export interface QuickActionMutationPlan {
+    readonly expectedRevision: string;
+    readonly next: QuickActionSettingsV1;
+    /** False when the plan would persist exactly what is already stored. */
+    readonly changed: boolean;
+}
+/** Why a planner refused; each reason maps to one management-panel response (spec 10). */
+export type QuickActionMutationRejectionReason = 
+/** One or more fields failed the shared validation rules. */
+'invalid-fields'
+/** Creating or cloning while the action total is at or above the ceiling. */
+ | 'limit-reached'
+/** The target action is absent, or is a tombstone this release must not touch. */
+ | 'unknown-action'
+/** The requested Custom Action ID is taken; mint another and retry. */
+ | 'id-in-use'
+/** The submitted order is not a permutation of the managed actions. */
+ | 'invalid-order';
+/** A refusal, with the field issues to render when the reason is a validation failure. */
+export interface QuickActionMutationRejection {
+    readonly reason: QuickActionMutationRejectionReason;
+    readonly issues: readonly QuickActionFieldIssue[];
+}
+/** Either a plan to persist behind the fence, or a refusal to show the user. */
+export type QuickActionMutationOutcome = {
+    readonly ok: true;
+    readonly plan: QuickActionMutationPlan;
+} | {
+    readonly ok: false;
+    readonly rejection: QuickActionMutationRejection;
+};
+/** The draft the management form opens on; the only place the confirm default is applied. */
+export declare function newQuickActionDraft(): QuickActionDraft;
+/** Create a Custom Quick Action under a caller-minted identity (spec 5.2, 5.4). */
+export declare function planCreateCustomQuickAction(context: QuickActionMutationContext, input: {
+    readonly id: CustomActionId;
+    readonly draft: QuickActionDraft;
+}): QuickActionMutationOutcome;
+/**
+ * Clone a Preset Quick Action into a new Custom Quick Action (spec 5.2).
+ * The confirmation policy is copied as it stands — including a Command Send
+ * Action the author left unconfirmed — never re-defaulted.
+ */
+export declare function planClonePresetQuickAction(context: QuickActionMutationContext, input: {
+    readonly presetId: PresetActionId;
+    readonly id: CustomActionId;
+}): QuickActionMutationOutcome;
+/**
+ * Save edited content onto an existing Custom Quick Action. `enabled` and the
+ * Clone Provenance survive the edit; `confirm` comes from the form, which is the
+ * only place the user can change it.
+ */
+export declare function planUpdateCustomQuickAction(context: QuickActionMutationContext, input: {
+    readonly id: CustomActionId;
+    readonly draft: QuickActionDraft;
+}): QuickActionMutationOutcome;
+/** Disable or re-enable a Custom Quick Action; disabled actions stay in the management panel (spec 3). */
+export declare function planSetCustomQuickActionEnabled(context: QuickActionMutationContext, input: {
+    readonly id: CustomActionId;
+    readonly enabled: boolean;
+}): QuickActionMutationOutcome;
+/** Delete a Custom Quick Action; normalization drops its order reference with it. */
+export declare function planDeleteCustomQuickAction(context: QuickActionMutationContext, input: {
+    readonly id: CustomActionId;
+}): QuickActionMutationOutcome;
+/** Hide or restore a Preset Quick Action; the author's definition is never touched (spec 5.1). */
+export declare function planSetPresetQuickActionHidden(context: QuickActionMutationContext, input: {
+    readonly presetId: PresetActionId;
+    readonly hidden: boolean;
+}): QuickActionMutationOutcome;
+/**
+ * Apply a new order to the actions the management panel lists. Preserved
+ * references — unknown presets and tombstones — keep their exact positions, so a
+ * reorder here never disturbs data a higher version owns.
+ */
+export declare function planReorderQuickActions(context: QuickActionMutationContext, input: {
+    readonly order: readonly QuickActionRef[];
+}): QuickActionMutationOutcome;
+/** Move one managed action to another position in the management list. */
+export declare function planMoveQuickAction(context: QuickActionMutationContext, input: {
+    readonly ref: QuickActionRef;
+    readonly toIndex: number;
+}): QuickActionMutationOutcome;
+/** Switch the global Quick Action Layout (spec 8.1). */
+export declare function planSetQuickActionLayout(context: QuickActionMutationContext, input: {
+    readonly layout: QuickActionLayout;
+}): QuickActionMutationOutcome;

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

@@ -0,0 +1,15 @@
+import type { PresetCatalog } from './catalog.js';
+import type { QuickActionSettingsV1 } from './types.js';
+/**
+ * Canonicalize one decoded snapshot against a catalog.
+ *
+ * Order: existing references keep their positions, minus repeats and minus
+ * references to custom actions that are gone; references to presets this catalog
+ * no longer carries stay put, because the same Preset Action ID coming back must
+ * restore the user's preference. Known actions with no reference are appended —
+ * presets in catalog order, then custom actions in stored order. Tombstones are
+ * never given a new reference, so a downgrade round trip returns their exact order.
+ */
+export declare function normalizeQuickActionSettings(settings: QuickActionSettingsV1, catalog: PresetCatalog): QuickActionSettingsV1;
+/** Decode a raw persisted value and canonicalize it in one step — the Host's read path. */
+export declare function readQuickActionSettings(raw: unknown, catalog: PresetCatalog): QuickActionSettingsV1;

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

@@ -0,0 +1,49 @@
+import type { PresetCatalog } from './catalog.js';
+import type { PresetActionId, QuickActionLayout, QuickActionRef, QuickActionSettingsV1 } from './types.js';
+/** Normal ceiling on known presets plus every custom action (spec 5.4). */
+export declare const QUICK_ACTION_TOTAL_LIMIT = 50;
+/** One action as the surfaces consume it, with its source-specific affordances resolved. */
+export interface ProjectedQuickAction {
+    readonly ref: QuickActionRef;
+    readonly label: string;
+    readonly text: string;
+    readonly icon: string | undefined;
+    readonly confirm: boolean;
+    /** Command Send Action: the text's first non-whitespace character is `/` (spec 4.3). */
+    readonly command: boolean;
+    /** Presets are author-owned: the user may reorder, hide and clone them, never edit them. */
+    readonly editable: boolean;
+    /** Hidden preset or disabled custom action: management panel only (spec 3). */
+    readonly hidden: boolean;
+    readonly clonedFromPresetId: PresetActionId | undefined;
+}
+/** The numbers the management panel gates its entry points and warnings on (spec 5.4). */
+export interface QuickActionCounts {
+    /** Known presets plus every custom action; hidden and disabled ones included. */
+    readonly total: number;
+    readonly limit: number;
+    /** `total` already above `limit` — a passive overflow that never drops data. */
+    readonly overflow: boolean;
+    /** Whether creating or cloning is allowed right now. */
+    readonly canAdd: boolean;
+    readonly visible: number;
+    readonly hidden: number;
+    /** Entries preserved but kept out of every projection: unknown presets and tombstones. */
+    readonly preserved: number;
+}
+/** Everything the surfaces and the management panel derive from one snapshot. */
+export interface QuickActionProjection {
+    readonly layout: QuickActionLayout;
+    /** Everything the management panel lists, in the shared order. */
+    readonly managed: readonly ProjectedQuickAction[];
+    /** The subset the Composer renders, in the same order. */
+    readonly composer: readonly ProjectedQuickAction[];
+    readonly counts: QuickActionCounts;
+}
+/**
+ * Project one snapshot against a catalog. The snapshot is canonicalized first, so
+ * the counts are the real totals even when the caller hands over state the catalog
+ * has moved on from — a known preset or a live action missing from the order must
+ * never slip past the action ceiling.
+ */
+export declare function projectQuickActions(raw: QuickActionSettingsV1, catalog: PresetCatalog): QuickActionProjection;

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

@@ -0,0 +1,48 @@
+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.
+ */
+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).
+ */
+export declare const QUICK_ACTIONS_CATALOG_NAMESPACE = "composer-quick-actions-catalog";
+/** The state a fresh install starts from (spec 4.2). */
+export declare const DEFAULT_QUICK_ACTION_SETTINGS: QuickActionSettingsV1;
+/**
+ * Whether a stored entry is a live Send Action this release can render.
+ * Everything else is a tombstone: a higher version's `kind`, or a value whose
+ * label/text are not readable strings.
+ */
+export declare function isLiveQuickAction(value: StoredQuickActionValue): value is CustomQuickActionValue;
+/** Whether a stored entry must be preserved untouched and kept out of every projection (spec 5.3). */
+export declare function isQuickActionTombstone(value: StoredQuickActionValue): value is QuickActionTombstone;
+/**
+ * Read one stored custom action into canonical form. A missing `kind` reads as
+ * `'send'` because V1 always writes the tag; anything else marks a tombstone and
+ * is handed straight back by identity, so a value written by a higher version
+ * survives the round trip intact.
+ *
+ * A live result always carries `kind`, `confirm` and `enabled` explicitly, which
+ * is what spec 4.3 requires of every normalized action. `confirm` is only
+ * defaulted when it is absent — never derived from the text.
+ */
+export declare function decodeStoredQuickAction(value: unknown): StoredQuickActionValue | undefined;
+/**
+ * Canonicalize one preset state: `hidden` becomes an explicit boolean or
+ * disappears, and every other field is carried through so a higher version's own
+ * preference survives a downgrade (spec 5.3).
+ */
+export declare function canonicalPresetState(state: Readonly<Record<string, unknown>>): PresetQuickActionState;
+/** Whether a canonical preset state carries no user preference at all. */
+export declare function isEmptyPresetState(state: PresetQuickActionState): boolean;
+/**
+ * Decode any published snapshot into V1. The stored `schemaVersion` is not a
+ * gate: a snapshot written by a higher version still yields every field this
+ * release understands, which is what makes a downgrade round trip lossless.
+ */
+export declare function decodeQuickActionSettings(raw: unknown): QuickActionSettingsV1;

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

@@ -0,0 +1,28 @@
+/**
+ * Unicode primitives shared by every Quick Action entry point (spec 4.3).
+ * Config loading, the management form, migration and Settings mutations must all
+ * measure and trim text through these functions so one rule cannot drift from another.
+ */
+/** Unicode code point length — the counting unit for every length limit (spec 4.3). */
+export declare function countCodePoints(value: string): number;
+/** Whether a text holds no character outside ECMAScript `trim()` whitespace (spec 4.3). */
+export declare function isBlankQuickActionText(text: string): boolean;
+/** Whether a text carries a DSH-reserved reference placeholder code point (spec 4.3). */
+export declare function containsReservedReferencePlaceholder(text: string): boolean;
+/**
+ * Whether a static text is a Command Send Action: its first non-whitespace
+ * character is `/` (spec 4.3). Whitespace is ECMAScript `trim()` whitespace.
+ */
+export declare function isCommandSendActionText(text: string): boolean;
+/** Grapheme-cluster reading of an icon candidate (spec 4.3). */
+export interface EmojiClusterScan {
+    /** Grapheme clusters in the candidate, emoji or not. */
+    readonly clusters: number;
+    /** Whether every grapheme cluster is an emoji cluster. */
+    readonly emojiOnly: boolean;
+}
+/**
+ * Segment an icon candidate into grapheme clusters and report whether each one
+ * is an emoji cluster, so validation can tell `too-long` from `not-emoji`.
+ */
+export declare function scanEmojiClusters(icon: string): EmojiClusterScan;

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

@@ -0,0 +1,89 @@
+/**
+ * Normalized Quick Action domain types (spec 4.1, 4.2) plus the field-issue
+ * vocabulary every validation entry point reports through (spec 4.3).
+ * Every type here is plain JSON: no cordis, React, DOM or storage handles.
+ */
+/** Author-assigned, package-scoped, permanent identity of a Preset Quick Action. */
+export type PresetActionId = string;
+/** UUID minted when a Custom Quick Action is created; stable for its whole life. */
+export type CustomActionId = string;
+/**
+ * Action-type discriminant. The first release is always `'send'`; it is not a
+ * configuration field. Keeping the tag lets a later Insert Action ship without
+ * raising `schemaVersion` or rewriting stored user data (spec 4.1, 16.1).
+ */
+export type QuickActionKind = 'send';
+/** The three global Quick Action Layouts (spec 8.1). */
+export type QuickActionLayout = 'ribbon' | 'bar' | 'launcher';
+/** Every layout value, in the order the management panel offers them. */
+export declare const QUICK_ACTION_LAYOUTS: readonly QuickActionLayout[];
+/** Author-owned, user-read-only action from the Preset Catalog (spec 4.1). */
+export interface PresetQuickAction {
+    readonly id: PresetActionId;
+    readonly kind: QuickActionKind;
+    readonly label: string;
+    readonly text: string;
+    readonly icon?: string;
+    readonly confirm: boolean;
+}
+/** User-owned action stored in Settings (spec 4.1). */
+export interface CustomQuickActionValue {
+    readonly kind: QuickActionKind;
+    readonly label: string;
+    readonly text: string;
+    readonly icon?: string;
+    readonly confirm: boolean;
+    readonly enabled: boolean;
+    readonly clonedFromPresetId?: PresetActionId;
+}
+/**
+ * A stored custom entry this release cannot render: its `kind` is not `'send'`
+ * (real data from a higher version) or its label/text are not readable strings.
+ * Preserved verbatim — never displayed, counted, edited or rewritten (spec 5.3).
+ * Every field stays opaque on purpose, `kind` included: this release must hand
+ * the record back to the version that wrote it exactly as it found it.
+ */
+export interface QuickActionTombstone {
+    readonly [field: string]: unknown;
+}
+/** One entry of `userActionsById`: either a live send action or a preserved tombstone. */
+export type StoredQuickActionValue = CustomQuickActionValue | QuickActionTombstone;
+/** Reference into the single mixed order shared by presets and custom actions (spec 4.1). */
+export type QuickActionRef = {
+    readonly source: 'preset';
+    readonly id: PresetActionId;
+} | {
+    readonly source: 'custom';
+    readonly id: CustomActionId;
+};
+/**
+ * The identity of a reference as one comparable string. Source and id together
+ * are the identity: the same id under a different source is a different action.
+ */
+export declare function quickActionRefKey(ref: QuickActionRef): string;
+/**
+ * User difference stored against one Preset Action ID (spec 4.2). `hidden` is the
+ * only field this release writes; any other field belongs to the version that
+ * wrote it and is carried through untouched.
+ */
+export interface PresetQuickActionState {
+    readonly hidden?: boolean;
+    readonly [field: string]: unknown;
+}
+/** The only persisted namespace shape (spec 4.2). */
+export interface QuickActionSettingsV1 {
+    readonly schemaVersion: 1;
+    readonly layout: QuickActionLayout;
+    readonly userActionsById: Readonly<Record<CustomActionId, StoredQuickActionValue>>;
+    readonly actionOrder: readonly QuickActionRef[];
+    readonly presetStateById: Readonly<Record<PresetActionId, PresetQuickActionState>>;
+}
+/** Fields a validation issue can be attached to. */
+export type QuickActionField = 'id' | 'kind' | 'label' | 'text' | 'icon' | 'confirm' | 'enabled' | 'clonedFromPresetId';
+/** Why a field was rejected. Combined with `field` it addresses one dictionary entry. */
+export type QuickActionIssueReason = 'invalid-type' | 'missing' | 'blank' | 'too-long' | 'reserved-placeholder' | 'not-emoji' | 'duplicate' | 'unsupported';
+/** One field-level rejection, reported identically by config loading, forms and mutations. */
+export interface QuickActionFieldIssue {
+    readonly field: QuickActionField;
+    readonly reason: QuickActionIssueReason;
+}

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

@@ -0,0 +1,40 @@
+import type { QuickActionFieldIssue } from './types.js';
+/** Label limit, in Unicode code points, measured after trimming (spec 4.3). */
+export declare const QUICK_ACTION_LABEL_MAX_CODE_POINTS = 40;
+/** Static text limit, in Unicode code points, measured without trimming (spec 4.3). */
+export declare const QUICK_ACTION_TEXT_MAX_CODE_POINTS = 4000;
+/** Icon limit, in emoji grapheme clusters (spec 4.3). */
+export declare const QUICK_ACTION_ICON_MAX_CLUSTERS = 4;
+/** What the management form edits; an empty `icon` means the action has no icon. */
+export interface QuickActionDraft {
+    readonly label: string;
+    readonly text: string;
+    readonly icon: string;
+    readonly confirm: boolean;
+}
+/** The stored content of a validated draft, shared by preset and custom actions. */
+export interface QuickActionContent {
+    readonly label: string;
+    readonly text: string;
+    readonly icon: string | undefined;
+    readonly confirm: boolean;
+}
+/** Either the content to persist, or every field that has to be fixed first. */
+export type QuickActionDraftResult = {
+    readonly ok: true;
+    readonly value: QuickActionContent;
+} | {
+    readonly ok: false;
+    readonly issues: readonly QuickActionFieldIssue[];
+};
+/** Trimmed label, or the reason it cannot be stored. */
+export declare function labelIssue(label: string): QuickActionFieldIssue | undefined;
+/** The reason a static text cannot be stored, if any. */
+export declare function textIssue(text: string): QuickActionFieldIssue | undefined;
+/** The reason a non-empty icon cannot be stored, if any. */
+export declare function iconIssue(icon: string): QuickActionFieldIssue | undefined;
+/**
+ * Validate one edited or created action. Issues come back in field declaration
+ * order — label, text, icon — so the form can render them deterministically.
+ */
+export declare function validateQuickActionDraft(draft: QuickActionDraft): QuickActionDraftResult;