austere-axi 0.2.0 → 0.4.0

package/types/catalog.d.ts

@@ -0,0 +1,82 @@
+// Types for the component catalog (src/shared/catalog.js) and the catalog.json
+// a pack ships. Hand-written. Keep it in step with CATALOG_FORMAT.
+
+export declare const CATALOG_FORMAT: 1;
+
+export type Tier = "core" | "extended";
+
+export interface CatalogEntry {
+  name: string;
+  group: string;
+  signature: string;
+  description: string;
+  tier: Tier;
+  /** "core", or the name of the pack that owns the component. */
+  pack: string;
+  examples: string[];
+}
+
+export interface CatalogGroup {
+  name: string;
+  notes: string[];
+}
+
+export interface Catalog {
+  format: typeof CATALOG_FORMAT;
+  pack: string;
+  version: string;
+  groups: CatalogGroup[];
+  components: CatalogEntry[];
+}
+
+/** What a pack's dist/catalog.json holds: the catalog plus the pack-only fields. */
+export interface PackCatalog extends Omit<Catalog, "components"> {
+  /** Pack API version the bundle targets. */
+  api: number;
+  /** `sha384-<base64>` of dist/pack.js. */
+  integrity: string;
+  /** Size of dist/pack.js in bytes. */
+  size: number;
+  /** True when the pack ships CSS. */
+  css: boolean;
+  components: (CatalogEntry & { slots: string[] | null })[];
+  /** JSON schema $defs reachable from the pack's components. */
+  defs: Record<string, unknown>;
+}
+
+export interface SpecGroup {
+  name: string;
+  components: string[];
+  notes?: string[];
+}
+
+/** The part of an OpenUI `library.toSpec()` result that the catalog reads. */
+export interface LibrarySpec {
+  components: Record<string, { signature: string; description?: string }>;
+  componentGroups?: SpecGroup[];
+}
+
+export interface CatalogFromSpecOptions {
+  pack?: string;
+  version?: string;
+  tiers?: Record<string, string>;
+  examples?: Record<string, string[]>;
+  /** Keep just these components (a pack's own, out of a library that also holds the core). */
+  only?: string[] | null;
+}
+
+export declare function catalogFromSpec(spec: LibrarySpec, options?: CatalogFromSpecOptions): Catalog;
+
+/** The spec the prompt is generated from: extended-tier components leave it. */
+export declare function promptSpec<S extends LibrarySpec>(spec: S, tiers?: Record<string, string>): S;
+
+export interface SearchOptions {
+  notesOf?: (entry: CatalogEntry) => string[];
+  limit?: number;
+}
+
+export declare function searchCatalog(
+  entries: CatalogEntry[],
+  query: string,
+  options?: SearchOptions,
+): { entry: CatalogEntry; score: number }[];

package/types/pack-kit.d.ts

@@ -0,0 +1,46 @@
+// Types for the pack kit (src/pack-kit/index.js, shipped as dist/pack-kit.mjs).
+import type { PackCatalog } from "./catalog.js";
+
+export { PACK_API, CONTENT_SLOTS } from "./pack.js";
+
+export declare const ENTRY_CANDIDATES: string[];
+
+export interface PackageJson {
+  name?: string;
+  version?: string;
+  austere?: { entry?: string };
+  [key: string]: unknown;
+}
+
+export declare function readPackageJson(dir: string): PackageJson;
+
+/** The pack's entry module: package.json "austere.entry", else the first of ENTRY_CANDIDATES. */
+export declare function packEntry(dir: string, pkg?: PackageJson): string;
+
+export declare function sri(buffer: Uint8Array): string;
+
+export interface BuildPackOptions {
+  /** Pack folder (package.json + entry module). */
+  dir: string;
+  /** The esbuild module to bundle with. */
+  esbuild: { build(options: any): Promise<unknown> };
+  /** Default <dir>/dist. */
+  outDir?: string;
+  /** Default package.json name. */
+  name?: string;
+  /** Default package.json version. */
+  version?: string;
+  /** Core component names, to warn about collisions. */
+  coreNames?: string[];
+  /** Default true. */
+  minify?: boolean;
+}
+
+export interface BuildPackResult {
+  catalog: PackCatalog;
+  warnings: string[];
+  packFile: string;
+  catalogFile: string;
+}
+
+export declare function buildPack(options: BuildPackOptions): Promise<BuildPackResult>;

package/types/pack.d.ts

@@ -0,0 +1,104 @@
+// Types for "austere-axi/pack": what a component pack imports. Hand-written
+// to match src/runtime/pack-api.js and src/runtime/define.js.
+import type { ZodObject, ZodRawShape, infer as ZodInfer } from "zod";
+
+export type { Catalog, CatalogEntry, PackCatalog, Tier } from "./catalog.js";
+
+/** Version of the pack API. A pack built for another major version is refused. */
+export declare const PACK_API: 1;
+
+/** Slots a content component may fill besides a Stack: "Card.children" and so on. */
+export declare const CONTENT_SLOTS: readonly string[];
+
+/** What a renderer receives. `renderNode` renders a child value from the parsed program. */
+export interface RendererArgs<Props> {
+  props: Props;
+  renderNode: (value: unknown) => unknown;
+  statementId?: string;
+}
+
+export interface ComponentSpec<Shape extends ZodRawShape = ZodRawShape> {
+  /** PascalCase name the agent writes. */
+  name: string;
+  /** A stock group (Layout, Content, Data, Charts, Forms, Buttons) or a short capitalized category of your own. */
+  group: string;
+  /** zod props in positional order. Append-only once published. */
+  props: ZodObject<Shape>;
+  /** One line the agent reads in `spec`. */
+  description: string;
+  /** React component: ({ props, renderNode, statementId }) => node. */
+  renderer: (args: RendererArgs<ZodInfer<ZodObject<Shape>>>) => unknown;
+  /** OpenUI statements; the first calls this component. Required unless `slots` is null. */
+  example?: string | string[];
+  /** Like `example`, with hostile input. Never in the prompt. */
+  stress?: string | string[];
+  /** Extra prompt lines, each starting with "- ". */
+  notes?: string[];
+  /** Parent slots it may fill; null for value-only sub-components. */
+  slots?: string[] | null;
+  /** Wrap the output with its statement name. Default true. */
+  tagged?: boolean;
+  /** "extended" keeps it out of the prompt. Default "core". */
+  tier?: "core" | "extended";
+}
+
+/** What austereComponent() returns. Put `definition.ref` in another component's props to nest it. */
+export interface AustereComponent {
+  name: string;
+  group: string;
+  notes: string[];
+  slots: string[] | null;
+  tagged: boolean;
+  tier: "core" | "extended";
+  example: string[] | null;
+  stress: string[] | null;
+  definition: {
+    ref: any;
+    [key: string]: any;
+  };
+}
+
+export declare function austereComponent<Shape extends ZodRawShape>(spec: ComponentSpec<Shape>): AustereComponent;
+
+/** What a pack's entry module default-exports. */
+export interface PackModule {
+  components: AustereComponent | AustereComponent[];
+  /** CSS text the runtime adds to the page once. */
+  css?: string;
+}
+
+export interface PackRegistration {
+  name: string;
+  version: string;
+  /** Defaults to PACK_API. */
+  api?: number;
+  components: AustereComponent | (AustereComponent | AustereComponent[])[];
+  css?: string;
+}
+
+export interface RegisteredPack {
+  name: string;
+  version: string;
+  components: AustereComponent[];
+  css: string;
+}
+
+/** Called once by each pack bundle when it loads. The pack kit adds this call for you. */
+export declare function registerPack(pack: PackRegistration): RegisteredPack;
+
+/** Packs registered so far, in load order. */
+export declare function registeredPacks(): RegisteredPack[];
+
+export declare function onPackRegistered(fn: (pack: RegisteredPack) => void): () => boolean;
+
+/** URL of a runtime asset next to austere.js, or "" when the page is inlined (export). */
+export declare function assetUrl(name: string): string;
+
+export interface RuntimeError {
+  source: string;
+  message: string;
+  statementId?: string;
+  [key: string]: unknown;
+}
+
+export declare function reportRuntimeError(err: RuntimeError): void;