@digital-gravy/etch-public-api 0.7.3 → 0.8.0

package/README.md

@@ -254,6 +254,42 @@ etch.blocks.setAttribute(svgBlockId, 'src', '/icons/logo.svg');
 etch.blocks.setAttribute(svgBlockId, 'stripColors', 'true');
 ```
 
+### Skills
+
+`etch.skills` exposes the bundled, read-only authoring guides Etch ships (e.g.
+the Automatic.css conventions). They follow a **progressive-disclosure** model:
+`list()` returns lightweight summaries for discovery, `get()` loads the full
+guide body, and `getReference()` pulls an individual reference (subskill)
+document only when needed — mirroring how a tool driving the builder is meant to
+read them.
+
+```ts
+// Discover what's currently available
+const skills = etch.skills.list();
+//    └─ [{ name, description, metadata, references }, …]
+
+// Load the full guide for a relevant skill
+const acss = etch.skills.get('acss');
+console.log(acss?.content); // SKILL.md body as Markdown
+
+// Pull a reference document on demand
+for (const file of acss?.references ?? []) {
+	const doc = etch.skills.getReference('acss', file);
+	// …
+}
+```
+
+All three methods are **synchronous** and never hit the network — content is
+bundled at build time or generated from live page state. An unknown `name` or
+`file`, or a skill whose integration isn't active, returns `undefined` rather
+than throwing, so you can probe the surface without guarding every call.
+
+> The available set is **runtime-dependent**: a skill tied to an integration is
+> only listed when that integration is active (the ACSS skill appears only when
+> Automatic.css is present), and some references are generated on demand from
+> live page state. Always `list()` to see what is currently available rather
+> than assuming a fixed set.
+
 ### Types only
 
 Every contract type is exported and dependency-free, so you can use them
@@ -283,6 +319,7 @@ is imported.
     - **Loops** — `EtchLoopsApi`, `EtchLoop`, `EtchLoopConfig`, `BlockLoopBinding`, …
     - **Navigation** — `EtchNavigationApi`, `NavigationPlace`, `PostSummary`, `TemplateSummary`
     - **Fields** — `EtchFieldsApi`, `CustomField`, `CustomFieldGroup`, …
+    - **Skills** — `EtchSkillsApi`, `SkillSummary`, `SkillDetail`
     - **UI / History** — `EtchUiApi`, `EtchHistoryApi`, `ColorScheme`
 
 ## Versioning

package/dist/index.d.cts

@@ -1046,8 +1046,9 @@ interface EtchComponentsApi {
  * - `content-hub` — the pages/posts browser
  * - `style-manager` — the global style manager
  * - `loop-manager` — the loop manager
+ * - `asset-manager` — the asset (media) library
  */
-type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1212,6 +1213,83 @@ interface EtchFieldsApi {
     deleteValueAsync(postId: number, fieldKey: string): Promise<void>;
 }
 
+/**
+ * Skill definitions and the `etch.skills` API surface.
+ *
+ * Skills are bundled, read-only authoring guides the Etch builder ships (e.g.
+ * the Automatic.css conventions). They follow a progressive-disclosure model:
+ * a lightweight {@link SkillSummary} for discovery, a {@link SkillDetail} with
+ * the full guide body, and per-reference subskill documents loaded on demand.
+ *
+ * Tooling — an AI assistant driving the builder over `connectAs`, for example —
+ * is expected to `list()` the available skills, `get()` the relevant one, then
+ * pull individual references only when needed, mirroring how the documents are
+ * meant to be read.
+ *
+ * The set is **runtime-dependent**: a skill tied to an integration is only
+ * listed when that integration is active (e.g. the ACSS skill appears only when
+ * Automatic.css is present), and some references are generated on demand from
+ * live page state rather than bundled. Always `list()` to see what is currently
+ * available rather than assuming a fixed set.
+ */
+/** A skill's metadata, without the guide body (returned by `skills.list()`). */
+interface SkillSummary {
+    /**
+     * Stable identifier from the skill's frontmatter `name` (e.g. `acss`).
+     * Lowercase; used to address the skill in {@link EtchSkillsApi.get} and
+     * {@link EtchSkillsApi.getReference}. Note this is the frontmatter name, not
+     * the on-disk directory name.
+     */
+    name: string;
+    /**
+     * One-line summary of when the skill applies, from frontmatter `description`.
+     * Meant to be read at discovery time to decide whether to load the full body.
+     */
+    description: string;
+    /**
+     * Arbitrary key/value metadata from the skill's frontmatter `metadata` block
+     * (e.g. `acss_min_version`). Extensible — keys vary per skill, so narrow
+     * before reading a specific one.
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * Filenames of the skill's reference (subskill) documents, e.g.
+     * `['colors.md', 'spacing.md']`. Pass one to
+     * {@link EtchSkillsApi.getReference} to load its content. Derived from the
+     * files that actually ship, so it never drifts from what is available.
+     */
+    references: string[];
+}
+/** A skill including its full guide body (returned by `skills.get()`). */
+interface SkillDetail extends SkillSummary {
+    /**
+     * The skill's primary guide as Markdown, with the frontmatter block stripped.
+     * This is the `SKILL.md` body.
+     */
+    content: string;
+}
+/**
+ * Bundled, read-only authoring skills shipped with the builder.
+ *
+ * All three methods are synchronous and never hit the network — content is
+ * either bundled at build time or generated from live page state. Lookups by an
+ * unknown `name` or reference `file`, or for a skill whose integration is not
+ * currently active, return `undefined` rather than throwing, so callers can
+ * probe the surface without guarding every call.
+ */
+interface EtchSkillsApi {
+    /** All available skills as summaries (without their guide bodies). */
+    list(): SkillSummary[];
+    /** One skill including its guide body, by frontmatter `name`; `undefined` if unknown. */
+    get(name: string): SkillDetail | undefined;
+    /**
+     * The Markdown content of one reference (subskill) document, by skill `name`
+     * and reference `file` (as listed in {@link SkillSummary.references});
+     * `undefined` if either is unknown.
+     */
+    getReference(name: string, file: string): string | undefined;
+}
+
 /**
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
@@ -1345,6 +1423,8 @@ interface Etch {
     ui: EtchUiApi;
     /** Undo/redo of builder mutations. */
     history: EtchHistoryApi;
+    /** Bundled, read-only authoring skills (guides + reference subskills). */
+    skills: EtchSkillsApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
     /**
@@ -1440,4 +1520,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/dist/index.d.ts

@@ -1046,8 +1046,9 @@ interface EtchComponentsApi {
  * - `content-hub` — the pages/posts browser
  * - `style-manager` — the global style manager
  * - `loop-manager` — the loop manager
+ * - `asset-manager` — the asset (media) library
  */
-type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1212,6 +1213,83 @@ interface EtchFieldsApi {
     deleteValueAsync(postId: number, fieldKey: string): Promise<void>;
 }
 
+/**
+ * Skill definitions and the `etch.skills` API surface.
+ *
+ * Skills are bundled, read-only authoring guides the Etch builder ships (e.g.
+ * the Automatic.css conventions). They follow a progressive-disclosure model:
+ * a lightweight {@link SkillSummary} for discovery, a {@link SkillDetail} with
+ * the full guide body, and per-reference subskill documents loaded on demand.
+ *
+ * Tooling — an AI assistant driving the builder over `connectAs`, for example —
+ * is expected to `list()` the available skills, `get()` the relevant one, then
+ * pull individual references only when needed, mirroring how the documents are
+ * meant to be read.
+ *
+ * The set is **runtime-dependent**: a skill tied to an integration is only
+ * listed when that integration is active (e.g. the ACSS skill appears only when
+ * Automatic.css is present), and some references are generated on demand from
+ * live page state rather than bundled. Always `list()` to see what is currently
+ * available rather than assuming a fixed set.
+ */
+/** A skill's metadata, without the guide body (returned by `skills.list()`). */
+interface SkillSummary {
+    /**
+     * Stable identifier from the skill's frontmatter `name` (e.g. `acss`).
+     * Lowercase; used to address the skill in {@link EtchSkillsApi.get} and
+     * {@link EtchSkillsApi.getReference}. Note this is the frontmatter name, not
+     * the on-disk directory name.
+     */
+    name: string;
+    /**
+     * One-line summary of when the skill applies, from frontmatter `description`.
+     * Meant to be read at discovery time to decide whether to load the full body.
+     */
+    description: string;
+    /**
+     * Arbitrary key/value metadata from the skill's frontmatter `metadata` block
+     * (e.g. `acss_min_version`). Extensible — keys vary per skill, so narrow
+     * before reading a specific one.
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * Filenames of the skill's reference (subskill) documents, e.g.
+     * `['colors.md', 'spacing.md']`. Pass one to
+     * {@link EtchSkillsApi.getReference} to load its content. Derived from the
+     * files that actually ship, so it never drifts from what is available.
+     */
+    references: string[];
+}
+/** A skill including its full guide body (returned by `skills.get()`). */
+interface SkillDetail extends SkillSummary {
+    /**
+     * The skill's primary guide as Markdown, with the frontmatter block stripped.
+     * This is the `SKILL.md` body.
+     */
+    content: string;
+}
+/**
+ * Bundled, read-only authoring skills shipped with the builder.
+ *
+ * All three methods are synchronous and never hit the network — content is
+ * either bundled at build time or generated from live page state. Lookups by an
+ * unknown `name` or reference `file`, or for a skill whose integration is not
+ * currently active, return `undefined` rather than throwing, so callers can
+ * probe the surface without guarding every call.
+ */
+interface EtchSkillsApi {
+    /** All available skills as summaries (without their guide bodies). */
+    list(): SkillSummary[];
+    /** One skill including its guide body, by frontmatter `name`; `undefined` if unknown. */
+    get(name: string): SkillDetail | undefined;
+    /**
+     * The Markdown content of one reference (subskill) document, by skill `name`
+     * and reference `file` (as listed in {@link SkillSummary.references});
+     * `undefined` if either is unknown.
+     */
+    getReference(name: string, file: string): string | undefined;
+}
+
 /**
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
@@ -1345,6 +1423,8 @@ interface Etch {
     ui: EtchUiApi;
     /** Undo/redo of builder mutations. */
     history: EtchHistoryApi;
+    /** Bundled, read-only authoring skills (guides + reference subskills). */
+    skills: EtchSkillsApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
     /**
@@ -1440,4 +1520,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-public-api",
-	"version": "0.7.3",
+	"version": "0.8.0",
 	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
 	"license": "MIT",
 	"repository": {