@batterai/block-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @batterai/block-sdk — the framework-neutral block boundary (plan §4 L1).
+ * Lit-based base element + pure DSD server render + tag scheme + defineBlock.
+ * Imports contract + bind-core only (depcruise-enforced).
+ */
+export * from "./tag.js";
+export * from "./base-element.js";
+export * from "./define.js";
+export * from "./i18n.js";
+export * from "./render-to-dsd.js";
+export * from "./html-package.js";
+export * from "./blocks/callout.js";
+export * from "./blocks/first-party.js";
+export * from "./blocks/form.js";
+export * from "./blocks/image.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,OAAO,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/render-to-dsd.d.ts

@@ -0,0 +1,18 @@
+import { html } from "lit";
+import type { BlockConfig, BlockPackage } from "@batterai/contract";
+export declare function renderBlockToDSD(pkg: BlockPackage, rawConfig: BlockConfig): string;
+/** Assemble a React-free page around pre-rendered block HTML. The client
+ * bundle (when any block needs hydration) must import
+ * `@lit-labs/ssr-client/lit-element-hydrate-support.js` BEFORE element
+ * definitions (invariant A; Phase-1 finding). */
+export declare function assemblePage(opts: {
+    /** Omit (or pass "") when headExtra already carries a <title> — an empty
+     * duplicate <title></title> would win the browser's first-tag-counts rule. */
+    readonly title?: string;
+    readonly lang: string;
+    readonly blocksHtml: readonly string[];
+    readonly clientBundleSrc?: string;
+    readonly headExtra?: string;
+}): string;
+export { html };
+//# sourceMappingURL=render-to-dsd.d.ts.map

package/dist/render-to-dsd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-to-dsd.d.ts","sourceRoot":"","sources":["../src/render-to-dsd.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgBpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,GAAG,MAAM,CAwBlF;AAED;;;iDAGiD;AACjD,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC;kFAC8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,MAAM,CAUT;AAUD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/render-to-dsd.js

@@ -0,0 +1,72 @@
+/**
+ * Server render utilities (contract §7; invariant A). renderPageElementToDSD
+ * produces the FULL element markup with a Declarative Shadow DOM template via
+ * @lit-labs/ssr, from the SAME element definition the client hydrates —
+ * one template, byte-compatible output (proven in Phase 1 Leg 1; enforced by
+ * the fixture CI check here).
+ */
+import { render } from "@lit-labs/ssr";
+import { collectResultSync } from "@lit-labs/ssr/lib/render-result.js";
+import { html } from "lit";
+import { unsafeStatic, html as staticHtml } from "lit/static-html.js";
+import { tagFor } from "./tag.js";
+/** Render one block element (tag chosen from the manifest) with its config
+ * property bound, to a DSD-carrying HTML string. PURITY CONTRACT: the block's
+ * render must not touch window/document/Date.now — the same discipline
+ * bind-core's resolver already enforces upstream (resolved values only). */
+/** Invariant L, enforced structurally: renderToDSD is the PUBLIC path — the
+ * editor canvas mounts client-side. Editor-session context (editingRegion,
+ * bindings, selected) is STRIPPED before serialization so an overlay session
+ * cannot leave any trace in published bytes, and editMode is forced false. */
+function publicConfig(config) {
+    const { editingRegion: _er, bindings: _b, selected: _s, api: _a, ...rest } = config.context;
+    return { ...config, context: { ...rest, editMode: false } };
+}
+export function renderBlockToDSD(pkg, rawConfig) {
+    const config = publicConfig(rawConfig);
+    const serializedConfig = {
+        ...config,
+        data: config.data.resources?.__blockRuntime
+            ? { ...config.data, resources: Object.fromEntries(Object.entries(config.data.resources).filter(([key]) => key !== "__blockRuntime")) }
+            : config.data,
+    };
+    const tag = tagFor(pkg.manifest.type, pkg.manifest.version);
+    // renderToDSD on the package (author-supplied pure string path) wins when
+    // present; otherwise the element itself is SSR'd via lit-labs.
+    if (pkg.renderToDSD) {
+        const inner = pkg.renderToDSD(config);
+        if (pkg.renderMode === "light") {
+            return `<${tag} config="${escapeAttribute(JSON.stringify(serializedConfig))}">${inner}</${tag}>`;
+        }
+        return `<${tag} config="${escapeAttribute(JSON.stringify(serializedConfig))}"><template shadowrootmode="open">${inner}</template></${tag}>`;
+    }
+    pkg.defineElement();
+    const t = unsafeStatic(tag);
+    // Attribute (not property) binding: survives DSD serialization so the client
+    // hydrates from IDENTICAL data (see BatteryBlockElement.properties note).
+    const result = render(staticHtml `<${t} config=${JSON.stringify(config)}></${t}>`);
+    return collectResultSync(result);
+}
+/** Assemble a React-free page around pre-rendered block HTML. The client
+ * bundle (when any block needs hydration) must import
+ * `@lit-labs/ssr-client/lit-element-hydrate-support.js` BEFORE element
+ * definitions (invariant A; Phase-1 finding). */
+export function assemblePage(opts) {
+    return `<!doctype html>
+<html lang="${opts.lang}">
+<head><meta charset="utf-8">${opts.title ? `<title>${escapeTitle(opts.title)}</title>` : ""}${opts.headExtra ?? ""}</head>
+<body>
+${opts.blocksHtml.join("\n")}
+${opts.clientBundleSrc ? `<script type="module" src="${opts.clientBundleSrc}"></script>` : ""}
+</body>
+</html>
+`;
+}
+function escapeTitle(s) {
+    return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+}
+function escapeAttribute(s) {
+    return s.replace(/[&"<>]/g, (c) => ({ "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" })[c]);
+}
+export { html };
+//# sourceMappingURL=render-to-dsd.js.map

package/dist/render-to-dsd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-to-dsd.js","sourceRoot":"","sources":["../src/render-to-dsd.ts"],"names":[],"mappings":"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"}

package/dist/tag.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Element-tag scheme (plan §4): `be-<source>-<name>-v<major>`. First-party
+ * source id is `battery`, so first-party tags are `be-battery-…` — which is
+ * what keeps the tag scheme and the no-vendor-names test compatible. Per-major
+ * tags let two majors coexist (plan D7); tenant filtering is a HOST registry
+ * view, not a tag property (a display filter is not a security boundary).
+ */
+export declare function parseBlockType(type: string): {
+    source: string;
+    name: string;
+};
+export declare function majorOf(version: string): number;
+export declare function tagFor(type: string, version: string): string;
+//# sourceMappingURL=tag.d.ts.map

package/dist/tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../src/tag.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAQ7E;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D"}

package/dist/tag.js

@@ -0,0 +1,25 @@
+/**
+ * Element-tag scheme (plan §4): `be-<source>-<name>-v<major>`. First-party
+ * source id is `battery`, so first-party tags are `be-battery-…` — which is
+ * what keeps the tag scheme and the no-vendor-names test compatible. Per-major
+ * tags let two majors coexist (plan D7); tenant filtering is a HOST registry
+ * view, not a tag property (a display filter is not a security boundary).
+ */
+export function parseBlockType(type) {
+    const m = /^([a-z][a-z0-9]*)\.([a-z][a-z0-9-]*)$/.exec(type);
+    if (!m) {
+        throw new Error(`block type "${type}" must be "<source>.<name>" (lowercase, digits, hyphens in name)`);
+    }
+    return { source: m[1], name: m[2] };
+}
+export function majorOf(version) {
+    const m = /^(\d+)\./.exec(version);
+    if (!m)
+        throw new Error(`block version "${version}" is not semver`);
+    return Number(m[1]);
+}
+export function tagFor(type, version) {
+    const { source, name } = parseBlockType(type);
+    return `be-${source}-${name}-v${majorOf(version)}`;
+}
+//# sourceMappingURL=tag.js.map

package/dist/tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.js","sourceRoot":"","sources":["../src/tag.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,uCAAuC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,kEAAkE,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,OAAO,iBAAiB,CAAC,CAAC;IACpE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,OAAe;IAClD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9C,OAAO,MAAM,MAAM,IAAI,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@batterai/block-sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test:e2e": "bun harness/build-fixtures.ts && bun build harness/client.ts --outdir dist --target browser --production && playwright test",
+    "build": "node ../../scripts/build-package.mjs",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@batterai/bind-core": "^0.1.0",
+    "@batterai/contract": "^0.1.0",
+    "lit": "^3.2.0",
+    "@lit-labs/ssr": "^3.3.0",
+    "@lit-labs/ssr-client": "^1.1.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@types/node": "^22.13.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}