@mhome/app-facade-protocol 1.128.0 → 1.129.1

package/contract/card-skins-v1.md

@@ -65,8 +65,13 @@ Package caching does not install, select, upgrade, or grant additional device au
 All platforms retain the renderer isolation requirement, including for cached files.
 
 The publication service validates metadata and bytes, not JavaScript behavior.
-The renderer contract remains `apiVersion: 1` during development and changes in
-place. Hosts and skins use that current contract without a compatibility layer.
+The renderer contract is `apiVersion: 2`. Renderers supply content in a
+framework-owned surface, both standalone and embedded. The host owns background,
+radius, clipping, menus, editing and composition dividers. A content root stays
+transparent and uses the inherited foreground; the renderer may arrange its title,
+values and controls without a reserved header. Each member receives its own grid
+and measured content viewport. Whole-card API 1 packages are rejected and must be
+adapted and rebuilt; there is no legacy rendering mode.
 The authoring build verifies the bundled ESM structure; the browser host verifies
 renderer exports against the manifest before using them. Each base owns its
 presentation adapter and renderer host; common card state and actions do not

package/contract/dashboard-composition-v1.md

@@ -0,0 +1,59 @@
+# Canvas layout and card composition
+
+Canvas owns one versioned layout document for every Dashboard placement. Card
+bodies own content, views, business references and size-only `defaultSizes`.
+`cardIds`, absolute leaf positions and parent membership are read projections,
+never independent stored placement authorities. Physical Device parentage does
+not change this presentation model; arbitrary logical Cards can be composed.
+
+The layout schema is `schema/canvas-layout.v1.schema.json`. Root coordinates are
+Canvas-global; member coordinates are relative to their composition. Each item
+has independent sm/md/lg layouts, limited to 2/4/6 columns respectively. Members
+are leaf Card references, never nested compositions. IDs are unique and leaves
+cannot be placed twice. Siblings cannot overlap; children must fit within their
+outer rectangle. Coordinates use nonnegative signed-32-bit integers. The UTF-8
+layout document is at most 256 KiB.
+
+`/app/dashboard/canvas/content/get` returns all leaf definitions, `revision` and
+`layoutDocument`. Observations remain independent and do not advance layout
+revision. Opening the Dashboard or switching profiles never repacks a saved
+layout. Default dimensions are used only when creating a placement.
+
+## Commands
+
+All three composition commands require current-Space write authorization and
+`expectedRevision`. They return `{spaceId, canvasId, revision, layoutDocument}`;
+creation also returns `createdItemId`. The backend owns validation and the whole
+operation. A stale revision changes nothing. An optional `rootDrafts` array includes unsaved root placement changes for up to
+three distinct profiles in that same commit. `rootDraft` remains supported for a
+single profile; the two fields are mutually exclusive. Ordinary layout updates
+may include `rootDrafts` for profiles other than their main `layoutSize`; organize
+may include all edited profiles before arranging its selected profile.
+
+- `/app/dashboard/canvas/composition/create`: `itemIds` selects two or more roots.
+  Existing compositions flatten to leaves; leaf identities and current dimensions
+  remain. Fixed-pass first-fit packing compares original, area, height and width
+  order across available widths. Choose smaller bounding area, then greater
+  width, with deterministic ties. No rotations, resizing or optimality guarantee.
+  Place the resulting outer rectangle near the selection without moving others.
+- `/app/dashboard/canvas/composition/ungroup`: `compositionId` expands members
+  at outer-position plus local-position in every profile, preserving current size.
+- `/app/dashboard/canvas/composition/layout/update`: `compositionId`, `layoutSize`
+  and all `members` replace that profile's local layout. Alternatively `reset:true`
+  repacks within current outer width and height. Omit `members` when resetting.
+
+Ordinary drag, resize and organize also save Canvas layout and advance revision.
+Organize treats a composition as one root, keeping its internal layout intact.
+Group copy creates fresh container and Card IDs while retaining business refs;
+move preserves member identity and internal layout. Cross-Canvas move commits
+source and target Canvas documents together. Delete and resource cleanup prune
+leaf references: one surviving member becomes an independent Card at its current
+absolute position; zero members removes the container.
+
+Existing data is converted explicitly with old writers stopped, a verified
+backup and conflict checks. Runtime startup never converts legacy placement or
+silently deletes a database. Cloud Canvas records stay in the existing `canvas`
+table with unchanged primary keys. Existing records require an explicit in-place
+conversion and a verified backup before cutover. Aliyun must have local
+transactions enabled on that table; existing tables without the feature require
+provider support. No replacement Canvas table is introduced.

package/fixtures/card-skins/space.json

@@ -32,7 +32,7 @@
           "version": "1.0.0",
           "name": "Evening cards",
           "description": "Full-card skins for a color light, a playable speaker and a thermostat.",
-          "apiVersion": 1,
+          "apiVersion": 2,
           "entry": "skin.test.mjs",
           "renderers": [
             {