@brydio/manifest 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/requirements.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Two things every app must have before it is published (owner decisions of
+ * 22 September 2026), checked the same way by `brydio validate` and by
+ * `POST /apps/publish`.
+ *
+ * - **A logo and an icon, each in colour and in one colour** (ADR-A20). The
+ *   manifest names four image files, and a package missing any of them is
+ *   refused.
+ * - **Something for the assistant to call** (ADR-A19): generated tools from a
+ *   collection, a custom tool, an MCP server or an integration.
+ *
+ * A copy of Brydio's `apps/api/src/apps/manifest/requirements.ts`, the
+ * checks `POST /apps/publish` runs. Nothing here imports anything, so the
+ * copy is the file: not even `node:zlib`, which a PNG is inflated with, since
+ * a screen may bundle `@brydio/manifest` and a worker has none.
+ * `test/requirements.test.ts` asks Brydio the same questions whenever a
+ * checkout is beside this one.
+ *
+ * ## What "one colour" means
+ *
+ * The mono variant is drawn tinted by the theme, so it must be a shape and
+ * nothing else: one colour on transparency.
+ *
+ * - An **SVG** is read for every colour it paints with: `fill`, `stroke`,
+ *   `stop-color`, `flood-color` and `color`, as attributes and inside `style`.
+ *   `none`, `transparent`, `inherit` and `currentColor` are not colours.
+ *   A shape with no fill of its own paints in the default black, unless the
+ *   root `<svg>` or a `<g>` sets one. More than one distinct colour is
+ *   refused, and so is an embedded `<image>`, which could be anything.
+ * - A **PNG** is decoded, and every pixel at least 1/16 opaque must be within
+ *   32 of one colour on each channel, so anti-aliased edges of a black glyph
+ *   (black at partial alpha) pass and a two-colour picture does not. A PNG
+ *   with no transparent pixel at all is a solid block and is refused too.
+ * - A **JPEG** has no transparency, and a **WebP** is not decoded here, so
+ *   neither can be the one-colour variant. Both are fine in colour.
+ *
+ * ## Sizes
+ *
+ * - An **icon** is square: from 48 to 1,024 pixels across as a raster, and a
+ *   square view box as an SVG.
+ * - A **logo** may be wider than it is tall, never taller: from 48 to 1,024
+ *   pixels tall, at most 2,048 wide, and at most four times as wide as it is
+ *   tall. An SVG's view box is held to the same proportions.
+ * - Every file is at most 512 KB.
+ */
+export declare const BRAND_LIMITS: {
+    readonly bytes: number;
+    readonly iconMinSide: 48;
+    readonly iconMaxSide: 1024;
+    readonly logoMinHeight: 48;
+    readonly logoMaxHeight: 1024;
+    readonly logoMaxWidth: 2048;
+    /** Width over height, at most. */
+    readonly logoMaxRatio: 4;
+};
+/** The two images, and the two variants each one comes in. */
+export declare const BRAND_FIELDS: readonly ["logo.color", "logo.mono", "icon.color", "icon.mono"];
+export type BrandField = (typeof BRAND_FIELDS)[number];
+export type RequirementCode = 'brand_logo_missing' | 'brand_icon_missing' | 'brand_path_invalid' | 'brand_file_missing' | 'brand_file_too_large' | 'brand_file_unreadable' | 'brand_icon_shape' | 'brand_logo_shape' | 'brand_mono_type' | 'brand_mono_colours' | 'app_has_no_tools';
+export interface RequirementProblem {
+    code: RequirementCode;
+    message: string;
+    /** The manifest field, like `icon.mono`. */
+    path: string;
+}
+/** The files a check can see, by their path inside the package with no `./`. */
+export type RequirementFiles = ReadonlyMap<string, Uint8Array>;
+export type BrandImageType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml';
+/** A path the manifest wrote, as a bundle names the file: no `./`, forward slashes. */
+export declare const brandFilePath: (declared: string) => string;
+/**
+ * Whether a declared brand path is one Brydio will follow: `./`-prefixed,
+ * relative, inside the package, and a name a bundle can hold.
+ */
+export declare function isBrandPath(declared: unknown): declared is string;
+/**
+ * The brand files a manifest names, by field, as bundle paths. Only fields
+ * written in the two-variant shape; a legacy `icon: "./icon.png"` names none.
+ */
+export declare function brandPathsOf(manifest: unknown): Map<BrandField, string>;
+/**
+ * Everything wrong with an app's logo and icon.
+ *
+ * `required` is off only where a package is read that is not being published
+ * (an import of somebody's plugin with no screens): the images it does name
+ * are still checked, and the ones it leaves out are not asked for.
+ */
+export declare function brandProblems(manifest: Record<string, unknown>, files: RequirementFiles, options?: {
+    required?: boolean;
+}): RequirementProblem[];
+/**
+ * Whether the assistant has anything to call in this app (ADR-A19).
+ *
+ * `parts` counts what the package bundles beside the manifest: the servers in
+ * its `servers.json` and the files in its `integrations/`. Where they can't
+ * be seen (a published bundle holds only code), `requires` still counts.
+ */
+export declare function toolsProblem(manifest: Record<string, unknown>, parts?: {
+    servers?: number;
+    integrations?: number;
+}): RequirementProblem | null;
+export interface BrandShape {
+    type: BrandImageType;
+    width: number;
+    height: number;
+}
+/** What an image is and how big, from its bytes, or null for anything else. */
+export declare function brandShapeOf(bytes: Uint8Array): BrandShape | null;
+/** No script, no event handler, no `javascript:` and no reference that leaves the file. */
+export declare function svgIsInert(svg: string): boolean;
+/**
+ * Every distinct colour an SVG paints with, normalised, or null when it
+ * embeds a raster whose colours can't be read from the markup.
+ */
+export declare function svgColours(svg: string): string[] | null;
+/**
+ * What a PNG's pixels say about being one colour.
+ *
+ * Decodes the image (non-interlaced, every colour type and bit depth) and
+ * compares every pixel at least 1/16 opaque with the most opaque one.
+ */
+export declare function pngVerdict(bytes: Uint8Array): 'one' | 'colours' | 'opaque' | 'unreadable';