@oneie/sdk 0.14.11 → 0.14.13

package/README.md

@@ -48,6 +48,11 @@ highways.forEach(h => console.log(`${h.path}: ${h.net}`));
 | `@oneie/sdk/openapi` | `buildReceiverPayload()` — generate the receiver `oneOf` for `openapi.yaml` (`bun run generate:openapi`) |
 | `@oneie/sdk/client` | `SubstrateClient` as a direct subpath (skips the barrel) |
 | `@oneie/sdk/brain` | `BrainClient` — CF-Worker-safe substrate client (use this, never the bare barrel, in a Worker) |
+| `@oneie/sdk/blocks` | `normalizeBlockProps()` — land an agent's generated copy on the fields the block that RENDERS reads. Puck's family collapse unions every member's fields into one registration, so a prop can be declared, accepted and still invisible; this resolves the member and rewrites the keys onto its own vocabulary. Schema-agnostic: pass your own `BlockSchema` |
+| `@oneie/sdk/fn-allowlist` | The TypeQL functions callable through `fn()` — one list, so a caller and the gateway cannot disagree |
+| `@oneie/sdk/role-tiers` | `tierOf()` — the four rungs (`owner` · `admin` · `member` · `viewer`) as an ordered comparison |
+| `@oneie/sdk/role-actions` | `minTier()` — the per-action floor the tier is compared against |
+| `@oneie/sdk/receiver-action` | `receiverAction()` — the receiver a role-gated action resolves to |
 | `@oneie/sdk/gateway` | `GatewayClient` — typed client for the `api.one.ie` gateway |
 | `@oneie/sdk/types` | Type definitions only — `Outcome<T>`, `Signal`, and friends |
 | `@oneie/sdk/telemetry` | `emit()`, opt-out helpers — the anonymous usage-signal layer |
@@ -55,7 +60,7 @@ highways.forEach(h => console.log(`${h.path}: ${h.net}`));
 | `@oneie/sdk/work-contract` | Work-contract primitives — deterministic gate rails every page inherits |
 | `@oneie/sdk/market` | Marketplace helpers — list, hire, bounty |
 | `@oneie/sdk/billing` | Billing/credits helpers |
-| `@oneie/sdk/fetch` | `oneFetch()`, `createAgent()` — x402-aware fetch wrapper with budget guards (`PaymentError`, `BudgetExceededError`, `X402NetworkError`) |
+| `@oneie/sdk/fetch` | `oneFetch()`, `createAgent({ pay })` — x402-aware fetch wrapper. The buyer supplies its own `pay(option) => txHash` signer; the SDK never signs, never asks a server to pay, and holds no chain library. Without a signer a 402 throws `PaymentError`. `~/.oneie/budget.json` is an **advisory** self-ledger, not a control (`PaymentError`, `BudgetExceededError`, `X402NetworkError`) |
 | `@oneie/sdk/templates` | `TEMPLATES`, `tqlToManifest()`, `BASE_MANIFEST` — scaffold manifests for `oneie create` |
 | `@oneie/sdk/generated/fn-map` | Generated TypeQL function map — backs the CLI's `fn run` and MCP's `fn.ts` tools |
 | `@oneie/sdk/generated/skins/engineering` | Generated skin vocabulary map |

package/dist/.build-fingerprint

@@ -0,0 +1 @@
+838c0e63656afd0c9f2fde06926410fec459f840a8d04eec6b2cd81c256420db

package/dist/billing.d.ts

@@ -1,6 +1,7 @@
 /**
  * Billing helpers — pure, no I/O.
  *
+ * CREDITS_PER_USD: the canonical credit rate.
  * rateFor: convert OpenRouter KV blob pricing → platform credits per 1k tokens.
  * computeBurn: calculate billed amount from upstream cost + margin config.
  */
@@ -12,6 +13,17 @@ export type RateModel = {
 export type RateBlob = {
     models: RateModel[];
 };
+/**
+ * The credit rate. One thousand credits to the dollar, so 1 credit = $0.001.
+ * This is the only place the rate is declared. Import it, never retype it.
+ */
+export declare const CREDITS_PER_USD = 1000;
+/** The same rate read the other way, for pricing a single credit. */
+export declare const USD_PER_CREDIT: number;
+/** Convert dollars to credits. Rounds, because credits are whole units. */
+export declare function creditsForUsd(usd: number): number;
+/** Convert cents to credits. Stripe amounts arrive in cents. */
+export declare function creditsForCents(cents: number): number;
 /**
  * Convert a model's live OpenRouter pricing to platform credits per 1k tokens.
  * Pass the parsed KV blob (`openrouter:models:v1`) from the caller's KV read.

package/dist/billing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AACtF,MAAM,MAAM,QAAQ,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA;AAK9C;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GACvB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAgBjD;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE;QAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5F,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAwB5D"}
+{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AACtF,MAAM,MAAM,QAAQ,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,eAAe,OAAQ,CAAA;AAEpC,qEAAqE;AACrE,eAAO,MAAM,cAAc,QAAsB,CAAA;AAEjD,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GACvB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CA6BjD;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE;QAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5F,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAwB5D"}

package/dist/billing.js

@@ -1,11 +1,25 @@
 /**
  * Billing helpers — pure, no I/O.
  *
+ * CREDITS_PER_USD: the canonical credit rate.
  * rateFor: convert OpenRouter KV blob pricing → platform credits per 1k tokens.
  * computeBurn: calculate billed amount from upstream cost + margin config.
  */
-/** 1 credit = $0.0001 USD */
-const CREDITS_PER_USD = 10_000;
+/**
+ * The credit rate. One thousand credits to the dollar, so 1 credit = $0.001.
+ * This is the only place the rate is declared. Import it, never retype it.
+ */
+export const CREDITS_PER_USD = 1_000;
+/** The same rate read the other way, for pricing a single credit. */
+export const USD_PER_CREDIT = 1 / CREDITS_PER_USD;
+/** Convert dollars to credits. Rounds, because credits are whole units. */
+export function creditsForUsd(usd) {
+    return Math.round(usd * CREDITS_PER_USD);
+}
+/** Convert cents to credits. Stripe amounts arrive in cents. */
+export function creditsForCents(cents) {
+    return creditsForUsd(cents / 100);
+}
 /**
  * Convert a model's live OpenRouter pricing to platform credits per 1k tokens.
  * Pass the parsed KV blob (`openrouter:models:v1`) from the caller's KV read.
@@ -18,13 +32,26 @@ export function rateFor(modelId, kvBlob) {
         if (m?.promptPrice) {
             const pIn = parseFloat(m.promptPrice);
             const pOut = m.completionPrice ? parseFloat(m.completionPrice) : pIn * 3;
+            // NOT rounded. A rate is not money yet, and rounding one to a whole
+            // credit here throws away the cheap end of the model list: at 1,000
+            // credits to the dollar, gpt-4o-mini input prices at 0.15 credits per
+            // 1k tokens, which rounds to zero, and haiku at 0.8 rounds to 1 — a 25%
+            // overcharge. Both callers already divide by 1,000 and round at the
+            // charge (api/chat.ts upstreamCredits, channels/cost-estimate.ts), which
+            // is the only place rounding belongs.
             return {
-                input_per_1k: Math.round(pIn * 1_000 * CREDITS_PER_USD),
-                output_per_1k: Math.round(pOut * 1_000 * CREDITS_PER_USD),
+                input_per_1k: pIn * 1_000 * CREDITS_PER_USD,
+                output_per_1k: pOut * 1_000 * CREDITS_PER_USD,
             };
         }
     }
-    return { input_per_1k: 25, output_per_1k: 125 };
+    // Fallback for a model the blob does not carry. Priced in dollars first so
+    // it keeps its meaning if the rate ever moves again: $0.0025 and $0.0125 per
+    // 1k tokens, which is the same money the old 25/125 meant at the old rate.
+    return {
+        input_per_1k: 0.0025 * CREDITS_PER_USD,
+        output_per_1k: 0.0125 * CREDITS_PER_USD,
+    };
 }
 export function computeBurn(p) {
     const platformPct = Math.max(p.config?.platform_margin_pct ?? 10, p.config?.platform_floor_pct ?? 5);

package/dist/billing.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing.js","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,6BAA6B;AAC7B,MAAM,eAAe,GAAG,MAAM,CAAA;AAE9B;;;;GAIG;AACH,MAAM,UAAU,OAAO,CACrB,OAAe,EACf,MAAwB;IAExB,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IAE5F,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QACxD,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;YACrC,MAAM,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAA;YACxE,OAAO;gBACL,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,GAAG,eAAe,CAAC;gBACvD,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,eAAe,CAAC;aAC1D,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,CAAA;AACjD,CAAC;AAwBD,MAAM,UAAU,WAAW,CAAC,CAAmB;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,CAAC,CAAC,MAAM,EAAE,mBAAmB,IAAI,EAAE,EACnC,CAAC,CAAC,MAAM,EAAE,kBAAkB,IAAI,CAAC,CAClC,CAAA;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5D,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAEzC,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,YAAY,CAAC,GAAG,GAAG,CAAC,CAAA;IACpE,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC,CAAA;IAC/D,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,GAAG,CAAC,CAAA;IACnE,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,CAAA;IAE1E,OAAO;QACL,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,cAAc,EAAE,MAAM;QACtB,YAAY,EAAE,CAAC,CAAC,QAAQ;QACxB,aAAa,EAAE,YAAY;QAC3B,eAAe,EAAE,cAAc;QAC/B,eAAe,EAAE,cAAc;QAC/B,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI;QAC9B,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI;KACvB,CAAA;AACH,CAAC"}
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["../src/billing.ts"],"names":[],"mappings":"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"}

package/dist/blocks.d.ts

@@ -0,0 +1,126 @@
+/**
+ * blocks.ts — land generated copy on the fields the block that RENDERS reads.
+ *
+ * One implementation, so a second one can never drift into the exact bug it
+ * exists to fix. `channels/src/tools/block-props.ts` binds it to the generated
+ * `BLOCK_SCHEMA` and `emit_block` calls it on every block it emits.
+ *
+ * Both call sites run it. `emit_block.execute` normalises the OUTPUT frame;
+ * `BlockFrame` (one.ie/web) normalises again at the frame, which is what covers
+ * the STREAMING preview — `MessageList` draws that from the model's partial tool
+ * input, before `execute` has seen it, so without this a mis-named prop painted
+ * placeholder copy for the length of the stream and snapped to the real text
+ * only at the end. The browser binds to a generated slim schema
+ * (`one.ie/web/src/lib/puck/block-schema.generated.ts`, third artifact of
+ * `.claude/scripts/blocks-manifest.mjs`, drift-gated by its `--check`): measured
+ * 7,104 bytes brotli added to a chat island that already statically imports the
+ * whole 320 KB Puck registry, which is why it is a static import and not the
+ * lazy one first planned against the 202 KB full manifest.
+ *
+ * The defect, measured 2026-08-19 against a real prod turn on https://one.ie
+ * ("Show me a hero section for a moving company called Zebra Movers"). The
+ * model wrote good copy and called the tool cleanly:
+ *
+ *   emit_block Hero { variant:'centered', headline:'Move with confidence.',
+ *     subheadline:'Zebra Movers makes local and long-distance moves simple…',
+ *     primaryCta:{label:'Get a free quote',href:'/quote'},
+ *     secondaryCta:{…}, badge:'Licensed & insured' }
+ *
+ * and the browser rendered HeroCentered's DEFAULTS — 0 of 6 generated fields
+ * visible (measured through the real registry: `heading`/`subheading`/
+ * `primaryCtaLabel`, all untouched). Two silent losses stacked:
+ *
+ *   1. Puck family collapse UNIONS every member's fields into one
+ *      registration, so `headline` is declared on the Hero family
+ *      (HeroVideoDialog reads it) and survives the declared-key filter — but
+ *      the member that renders variant 'centered' reads `heading`. Declared,
+ *      kept, and invisible: nothing drops, nothing warns.
+ *   2. `subheadline` and `badge` are not declared anywhere on the family, so
+ *      they are dropped outright. Same outcome, no signal.
+ *
+ * A model cannot guess this vocabulary — `Faq/default` takes `faqs[q|a]` while
+ * `Faq/simple` takes `items[question|answer]`, same family — so the fix is two
+ * halves and this file is the second: the tool PUBLISHES the per-variant field
+ * list so the first attempt is usually right, and `normalizeBlockProps` MAPS
+ * whatever still arrives under a synonym onto the member's real field. The
+ * mapping is not guesswork: a block declares its own `metadata.semantics`
+ * (role -> prop, 219 of 279 members do), and that declaration is consulted
+ * before any candidate list here.
+ *
+ * Refusal is still the answer where repair cannot reach — when NOTHING the
+ * model sent can land, `emit_block` rejects and names the legal fields.
+ */
+export interface BlockFieldSpec {
+    /** Puck field type — 'text' | 'textarea' | 'array' | 'select' | 'radio' | … */
+    type: string;
+    /** For `type: "array"` — the keys each ITEM object takes. */
+    of?: readonly string[];
+    /** For `type: "select" | "radio"` — the legal values. */
+    options?: readonly (string | number | boolean)[];
+}
+export interface BlockVariantSpec {
+    /** The fields the member that renders this variant actually reads. */
+    fields: Record<string, BlockFieldSpec>;
+    /** The block's own role -> prop declaration (heading/body/cta/image). */
+    semantics: Record<string, string>;
+    /**
+     * Props the RENDER reads that the editor's `fields` cannot express, keyed by
+     * the array field they belong to. Puck has no nested string-array, so
+     * `PricingSection` renders `tiers[].features` and can never declare it —
+     * without this the key exists, renders, and no agent is ever told about it
+     * (measured by `.claude/scripts/blocks-render-probe.mjs`). Absent on almost
+     * every member; three carry it today.
+     */
+    renders?: Record<string, readonly string[]>;
+}
+export interface BlockSchemaEntry {
+    /** The variant that renders when none is sent. null for a non-family block. */
+    canonicalVariant: string | null;
+    /** Keyed by variant value; the single key '' for a non-family block. */
+    variants: Record<string, BlockVariantSpec>;
+}
+export type BlockSchema = Record<string, BlockSchemaEntry>;
+/** Chrome fields — background/pattern/effect. Never content, always passed
+ * through untouched: the model may set them, but they can't carry copy and
+ * they must not count as "the payload landed". Exported because a caller
+ * deciding whether the model even TRIED to write copy has to ask the same
+ * question — a chrome-only call is a legitimate "render the default with this
+ * background", not a payload that failed to land. */
+export declare const CHROME_PROPS: ReadonlySet<string>;
+export interface NormalizedBlock {
+    /** The variant whose member the props were resolved against — `''` for a
+     * block that is not a collapsed family. */
+    variant: string;
+    /** Props rewritten onto that member's field names, `variant` preserved. */
+    props: Record<string, unknown>;
+    /** Member fields that received model-supplied content. Empty means the block
+     * would render pure defaults — the invisible-payload case. */
+    landed: string[];
+    /** Keys that mapped to no declared field, in the model's own spelling. They
+     * are PASSED THROUGH, not removed — a block can render a prop it never
+     * declared as an editor field. Reported so the caller can tell the model
+     * which of its names the registry does not know. */
+    unmapped: string[];
+    /** Every field the rendering member declares, for the rejection message. */
+    fields: string[];
+    /** Per-field detail (`type`, array item keys) for the rejection message. */
+    spec: Record<string, BlockFieldSpec>;
+}
+/**
+ * Resolve `props` against the member that `component` + `props.variant` really
+ * renders, and rewrite every key onto that member's vocabulary.
+ *
+ * A component with no schema entry passes through untouched — the table is
+ * generated from the live registry, and a name it doesn't know is one the
+ * renderer rejects downstream anyway.
+ */
+export declare function normalizeBlockProps(schema: BlockSchema, component: string, props?: Record<string, unknown>): NormalizedBlock;
+/** The field list as the model should read it back — same shape as
+ * BLOCK_FIELD_DOC's lines, so the rejection speaks the description's language. */
+export declare function describeFields(spec: Record<string, BlockFieldSpec>): string;
+/** The variants of `component` that declare at least one field — what to point
+ * a model at when it picked one that can carry no copy (`Hero/default` and
+ * `Pricing/default` are static blocks; both are the family canonical, so they
+ * are exactly what a no-variant call renders). */
+export declare function variantsWithFields(schema: BlockSchema, component: string): string[];
+//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtB,yDAAyD;IACzD,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAA;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACtC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAC3C;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAqB1D;;;;;qDAKqD;AACrD,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAiD,CAAA;AA4L9F,MAAM,WAAW,eAAe;IAC9B;+CAC2C;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B;kEAC8D;IAC9D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;wDAGoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,eAAe,CAyGjB;AAgBD;kFACkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAI3E;AAED;;;kDAGkD;AAClD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAMnF"}