[canvas-apps] Sync prompts from PA-Client

Author: joem-msft

plugins/canvas-apps/agents/canvas-app-planner.md

@@ -60,7 +60,7 @@ Read:
 
 - `${PLUGIN_ROOT}/references/YamlSyntax.md` — file structure, syntax rules, parse-error triage
 - `${PLUGIN_ROOT}/references/ControlGuide.md` — control selection, per-control properties, enums
-- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, colour contrast
+- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, color contrast
 - `${PLUGIN_ROOT}/references/PowerFxGuide.md` — state, events, named formulas, mock data
 - `${PLUGIN_ROOT}/references/DesignGuide.md` — aesthetic direction and design process
 - `${PLUGIN_ROOT}/references/PlanTemplates.md` — the exact shape of every artifact you write
@@ -89,6 +89,13 @@ ManualLayout.
    recorded, because the builder cannot look it up.
 5. Call API and schema detail tools only for resources involved in the edit.
 
+### Component refresh checkpoint
+
+Immediately before auditing properties, re-run `describe_control` for
+every Canvas or Code Component used by the plan to ensure any imported or updated components made in Studio are available.
+Especially if a successful compile applied local component-definition changes, since the previous lookup.
+Treat earlier component responses as stale; builders cannot refresh them.
+
 ## 3. Audit Control Properties
 
 Before writing plans:
@@ -151,7 +158,7 @@ clear navigation is cheaper than a screen that no builder can write correctly in
 and no user can scan. Prefer splitting by task (entry vs. history vs. analysis) rather
 than by control count.
 
-## 5. Specify the Narrow-Width Behaviour
+## 5. Specify the Narrow-Width Behavior
 
 Builders implement exactly what the brief specifies. If the brief describes only the
 desktop composition, the screen will break on a phone — this is the most frequently
@@ -168,7 +175,7 @@ For every screen brief, state explicitly:
 - That the root container scrolls (`LayoutOverflowY: =LayoutOverflow.Scroll`).
 - That the screen-level `Children:` list contains only that root, with every visible
   section nested under the root's `Children:` list.
-- The foreground colour for text on every coloured surface, so nothing renders
+- The foreground color for text on every colored surface, so nothing renders
   dark-on-dark.
 - A width or `LayoutMinWidth` for status badges and KPI values that fits the longest value
   they can display.
@@ -244,6 +251,12 @@ Do not edit any `.pa.yaml` file. Put all required app-level edits in the plan in
 
 If a group is empty, write `None` for it.
 
+### All modes
+
+Put requested screen or component-definition ordering in `## Editor State Changes` as
+the exact final `ScreensOrder` and `ComponentDefinitionsOrder` lists. Write `None` when
+the current Studio order should remain unchanged.
+
 ## 8. Write Progressive Plan Artifacts
 
 Follow `${PLUGIN_ROOT}/references/PlanTemplates.md`.
@@ -257,6 +270,7 @@ Write only orchestration information:
 - Compact discovery summary
 - Dispatch table
 - EDIT-mode App changes
+- Editor state changes
 
 The dispatch table columns are:
 
@@ -354,7 +368,7 @@ App compile: [Clean / diagnostics remaining, with detail]
 - Do not edit existing `.pa.yaml` files in EDIT mode.
 - Call `compile_canvas` only to validate CREATE-mode `App.pa.yaml`. Do not use it to
   chase screen-file diagnostics; the orchestrator owns full-app validation.
-- Do not edit `[working directory]/_EditorState.pa.yaml`.
+- Do not edit `[working directory]/_EditorState.pa.yaml`; record ordering work in `## Editor State Changes` for the top-level orchestrator.
 - Do not embed all discovery output in the index or shared plan.
 - Every screen brief must be self-sufficient when read with the shared plan.
 - Never assign two screens the same control name prefix.

plugins/canvas-apps/agents/canvas-screen-builder.md

@@ -165,7 +165,7 @@ incomplete, and the orchestrator will send the screen back.
 ## Constraints
 
 - Modify exactly one screen file.
-- Never edit `[working directory]/App.pa.yaml` or `[working directory]/_EditorState.pa.yaml`.
+- Do not edit `[working directory]/App.pa.yaml` or `[working directory]/_EditorState.pa.yaml`; the top-level orchestrator owns app-level and cross-file ordering changes.
 - Never substitute a filename, YAML key, or control name prefix.
 - Never use a property absent from that control's definition.
 - Never write a version suffix on a `Control:` value.

plugins/canvas-apps/references/ControlGuide.md

@@ -6,6 +6,7 @@ Choosing a control type, and writing properties and enum values that the compile
 ## Contents
 
 - Discover before you choose
+- Interpret property defaults and requirements
 - Layout containers
 - Data display
 - Selection controls — `ItemDisplayText` is a per-item formula
@@ -14,7 +15,7 @@ Choosing a control type, and writing properties and enum values that the compile
 - Enum type names
 - Enum member values
 - Option set values
-- Colour and button-state patterns
+- Color and button-state patterns
 - Timer lifecycle
 - Read-only ancestors
 - Cross-screen navigation
@@ -27,7 +28,26 @@ Choosing a control type, and writing properties and enum values that the compile
 **⚠️ Required — not optional:** run `list_controls` before planning your layout. Controls
 you don't know exist can't influence your design, and the catalog includes high-level
 controls (`ModernTabList`, `ModernCard`, and others) that are easy to miss and expensive
-to reinvent with primitives. Then run `describe_control` on every type you plan to use.
+to reinvent with primitives.
+
+The resulting list will also specify if any Code Components or Canvas Components are available as control instances in the app. The result identifies the `ComponentName` to pass to `describe_control`.
+
+Run `describe_control` on every type you plan to use.
+
+## Interpret property defaults and requirements
+
+The `Default` shown for a property is the value the property takes when it is omitted from the YAML.
+Properties marked `Required: true` must be provided, even when no default is shown.
+Omit other properties to accept their default.
+
+### Refresh Canvas and Code Component descriptions
+
+`describe_control` results for Canvas and Code Components are snapshots of the current
+Studio document, not durable catalog entries. Re-run `describe_control` for the returned
+`ComponentName` after a successful `compile_canvas` applies changes to a local component
+definition or its custom properties. Do not reuse component descriptions from an earlier
+turn after any of those events. Refresh immediately before recording component properties
+in a plan or editing a component instance.
 
 ## Layout containers
 
@@ -283,18 +303,18 @@ or starts with a number:
       Visible: =ThisItem.Status = 'Status (Assignments)'.Active
 ```
 
-## Colour and button-state patterns
+## Color and button-state patterns
 
 ```yaml
-# Colour constants
+# Color constants
 Fill: =Color.White
 BasePaletteColor: =Color.Blue
 
 # RGBA
 Fill: =RGBA(240, 240, 240, 1)
 FontColor: =RGBA(0, 0, 0, 1)
 
-# Conditional colour
+# Conditional color
 BasePaletteColor: =If(isActive, Color.Blue, Color.Gray)
 ```
 
@@ -303,18 +323,6 @@ and `Transparent` can remain light even when `Fill` is set. Pair those appearanc
 dark `Color`, or switch to `Primary` and set `BasePaletteColor` for a dark surface. Do not
 assume `Fill` overrides the variant.
 
-```yaml
-Properties:
-  DisplayMode: =If(isDisabled, DisplayMode.Disabled, DisplayMode.Edit)
-  Text: =buttonText
-  OnSelect: |-
-    =If(condition,
-      false,                           # Guard clause - do nothing
-      Set(variable, value);            # Execute logic
-      Set(anotherVar, anotherValue)
-    )
-```
-
 ## Timer lifecycle
 
 An automatic Timer needs a start edge after the control exists. If `AutoStart: =false`
@@ -361,13 +369,13 @@ replace `Badge.Content`; omitting Content can render placeholder text such as `A
 
 **Styling:**
 
-- `Fill` — background colour (absent on `Badge` and `Progress`)
-- `Color` — text colour on the modern React controls; `Badge` spells it `FontColor`
-- `BasePaletteColor` — theme colour for `Badge`, `Progress`, and the modern inputs
+- `Fill` — background color (absent on `Badge` and `Progress`)
+- `Color` — text color on the modern React controls; `Badge` spells it `FontColor`
+- `BasePaletteColor` — theme color for `Badge`, `Progress`, and the modern inputs
 - `Size` — font size on the modern React controls; `Badge` spells it `FontSize`
 - `FontWeight` — Bold, Semibold, Normal, Lighter
 
-**Behaviour:**
+**Behavior:**
 
 - `DisplayMode` — Edit, View, Disabled
 - `Visible` — boolean visibility
@@ -382,7 +390,7 @@ replace `Badge.Content`; omitting Content can render placeholder text such as `A
 - `LayoutGap` — spacing between items
 - `LayoutOverflowY` — vertical overflow (`Scroll` for scrollable containers)
 - `FillPortions` — proportional sizing
-- `PaddingTop/Bottom/Left/Right` — container padding
+- `PaddingTop`/`Bottom`/`Left`/`Right` — container padding
 
 ## Troubleshooting
 

plugins/canvas-apps/references/CreateWorkflow.md

@@ -8,7 +8,7 @@ Read:
 
 - `${PLUGIN_ROOT}/references/YamlSyntax.md` — file structure, syntax rules, parse-error triage
 - `${PLUGIN_ROOT}/references/ControlGuide.md` — control selection, per-control properties, enums
-- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, colour contrast
+- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, color contrast
 - `${PLUGIN_ROOT}/references/PowerFxGuide.md` — state, events, named formulas, mock data
 - `${PLUGIN_ROOT}/references/DesignGuide.md` — aesthetic direction and design process
 

plugins/canvas-apps/references/DesignGuide.md

@@ -62,7 +62,7 @@ the real user experience.
 - **Font Weight**: Use `ModernText` for headlines with `FontWeight: =FontWeight.Bold` and a large font size. Use `ModernText` with `FontWeight: =FontWeight.Normal` for body content.
 - **Size Contrast**: Create dramatic hierarchy with size differences. Headers at 24-32, subheaders at 18-20, body at 14-16.
 - **Alignment as Statement**: Mix `Align.Left`, `Align.Center`, `Align.Right` intentionally. Centered text for impact, left-aligned for readability.
-- **Font Properties**: Leverage `Size`, `FontWeight`, `Align`, `VerticalAlign`, and `Color` to create visual interest. On the modern React controls the text colour property is `Color` and the font size property is `Size` — `FontColor` and `FontSize` exist only on `Badge`. Confirm with `describe_control` rather than assuming.
+- **Font Properties**: Leverage `Size`, `FontWeight`, `Align`, `VerticalAlign`, and `Color` to create visual interest. On the modern React controls the text color property is `Color` and the font size property is `Size` — `FontColor` and `FontSize` exist only on `Badge`. Confirm with `describe_control` rather than assuming.
 
 ### Color & Visual Theme
 
@@ -80,7 +80,7 @@ the real user experience.
 - **Design for the narrowest width you claim to support**: A layout composed at 1440px and never re-checked will clip at 1024px and collapse on a phone. Size layout containers with `Parent.Width` or `FillPortions`, never a literal like `Width: =1120`. Reserve fixed pixel sizes for icons, avatars, and steppers — and keep interactive ones at 44px or larger.
 - **Every horizontal row of more than two controls needs a reflow strategy**: Set `LayoutWrap: =true`, or drive `LayoutDirection` from a width breakpoint, so rows stack instead of squeezing. This is the single most common defect in generated apps and it is invisible at the width you designed at.
 - **The screen root must scroll** whenever it holds a gallery, a form, or more than about three stacked sections: canvas screens do not scroll on their own, so give the root container `LayoutOverflowY: =LayoutOverflow.Scroll` and content below the fold stays reachable on short viewports.
-- **Set foreground wherever you set background**: Text does not inherit a contrasting colour. Every time you choose a container `Fill`, set `Color` on the text inside it — dark-on-dark passes every automated check and is unreadable.
+- **Set foreground wherever you set background**: Text does not inherit a contrasting color. Every time you choose a container `Fill`, set `Color` on the text inside it — dark-on-dark passes every automated check and is unreadable.
 - **Rows inside a `Gallery` need their own container**: `Gallery` is a Classic control and positions its template children absolutely, so a row authored at desktop width stays at desktop width everywhere. Put one AutoLayout `GroupContainer` in the template and build the row inside it. See `${PLUGIN_ROOT}/references/LayoutGuide.md`.
 - **Asymmetry & Breaking Grid**: Don't center everything. Offset elements. Use unexpected positioning.
 - **Spacing as Design**: Generous padding creates breathing room. Dense layouts create energy.

plugins/canvas-apps/references/EditWorkflow.md

@@ -19,7 +19,7 @@ Anything else is **complex**.
 
 1. Read `${PLUGIN_ROOT}/references/YamlSyntax.md`. Also read `${PLUGIN_ROOT}/references/ControlGuide.md` when the edit
    touches control properties or enums, and `${PLUGIN_ROOT}/references/LayoutGuide.md` when it touches
-   sizing, scrolling, or colour.
+   sizing, scrolling, or color.
 2. Use `describe_control` before adding a property not already present on that control.
 3. Apply targeted edits directly to the `[working directory]` folder.
 4. Read `${PLUGIN_ROOT}/references/ValidationWorkflow.md` and follow it.
@@ -31,7 +31,7 @@ Read:
 
 - `${PLUGIN_ROOT}/references/YamlSyntax.md` — file structure, syntax rules, parse-error triage
 - `${PLUGIN_ROOT}/references/ControlGuide.md` — control selection, per-control properties, enums
-- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, colour contrast
+- `${PLUGIN_ROOT}/references/LayoutGuide.md` — responsive layout, scrolling, color contrast
 - `${PLUGIN_ROOT}/references/PowerFxGuide.md` — state, events, named formulas, mock data
 - `${PLUGIN_ROOT}/references/DesignGuide.md` — aesthetic direction and design process
 

plugins/canvas-apps/references/LayoutGuide.md

@@ -1,6 +1,6 @@
-# Canvas App YAML — Layout and Responsive Behaviour
+# Canvas App YAML — Layout and Responsive Behavior
 
-Sizing, positioning, scrolling, and the narrow-width behaviour that decides whether a
+Sizing, positioning, scrolling, and the narrow-width behavior that decides whether a
 screen works on a phone. The defects in this guide are invisible at the width you author
 and are reported by no compile diagnostic.
 
@@ -13,7 +13,7 @@ and are reported by no compile diagnostic.
 - Galleries are Classic — their rows do not reflow
 - Horizontal rows must reflow at narrow widths
 - Give labelled controls room for their longest value
-- Text colour must be set wherever you set a background
+- Text color must be set wherever you set a background
 - Never hard-code a layout width
 - The screen root must be able to scroll
 - Layout rules of thumb
@@ -220,9 +220,9 @@ control sits in a horizontal row, set `FillPortions: =0` plus a `Width` (or
 `LayoutMinWidth`) that fits the longest value it can display, and set `Wrap: =false` on
 single-line text so it cannot silently become two lines.
 
-## Text colour must be set wherever you set a background
+## Text color must be set wherever you set a background
 
-Text controls do not inherit a contrasting colour from their container. A dark `Fill` with
+Text controls do not inherit a contrasting color from their container. A dark `Fill` with
 an unset `Color` renders near-black text on a near-black surface — technically valid and
 completely unreadable:
 

plugins/canvas-apps/references/PlanTemplates.md

@@ -43,6 +43,9 @@ CREATE
 |--------|--------|-------------|----------|-------------|--------------|
 | Create | [Landing] | `[working directory]/Screen1.pa.yaml` | Screen1 | [Prefix] | `[working directory]/Screen1.screen-plan.md` |
 | Create | [Additional] | `[working directory]/[Name].pa.yaml` | [Name] | [Prefix] | `[working directory]/[Name].screen-plan.md` |
+
+## Editor State Changes
+[Exact final ScreensOrder and ComponentDefinitionsOrder lists, or "None"]
 ```
 
 ## Plan Index — EDIT
@@ -81,6 +84,9 @@ EDIT
 seed data — or "None"]
 ### After builders
 [Changes referencing screens that do not exist yet, such as StartScreen — or "None"]
+
+## Editor State Changes
+[Exact final ScreensOrder and ComponentDefinitionsOrder lists, or "None"]
 ```
 
 ## Shared Plan

plugins/canvas-apps/references/QAChecks.md

@@ -43,7 +43,7 @@ are not part of the identifier.
 - Check 19 — `QACHK-NO-REFLOW` — horizontal row with no narrow-width strategy
 - Check 20 — `QACHK-ROOT-NOT-SCROLLABLE` — screen content taller than the viewport cannot
   be reached
-- Check 21 — `QACHK-LOW-CONTRAST-TEXT` — text colour not set against a coloured background
+- Check 21 — `QACHK-LOW-CONTRAST-TEXT` — text color not set against a colored background
 - Check 22 — `QACHK-VARIANT-SURFACE-CONTRAST` — light foreground on a variant-supplied
   surface
 - Check 23 — `QACHK-CARD-PLACEHOLDER` — `ModernCard` slot left unset
@@ -780,18 +780,18 @@ viewport.
 
 ---
 
-## Check 21 — `QACHK-LOW-CONTRAST-TEXT` (text colour not set against a coloured background)
+## Check 21 — `QACHK-LOW-CONTRAST-TEXT` (text color not set against a colored background)
 
-**Problem:** Text controls do not inherit a contrasting colour from their container. A
+**Problem:** Text controls do not inherit a contrasting color from their container. A
 container with a dark `Fill` whose child text controls omit `Color` renders near-black on
 near-black. `compile_canvas` passes it.
 
 **Detect:** For every container that sets a non-default `Fill`, check every descendant
 text control (`ModernText`, `Badge`, and any control with a `Text` or `Content` property)
-for an explicit colour — `Color` on the modern React controls, `FontColor` on `Badge`,
+for an explicit color — `Color` on the modern React controls, `FontColor` on `Badge`,
 `TitleColor`/`SubtitleColor`/`DescriptionColor` on `ModernCard`.
 
-**Fix:** Set the colour explicitly wherever the background was set:
+**Fix:** Set the color explicitly wherever the background was set:
 
 ```yaml
 Color: =RGBA(239, 246, 250, 1)

plugins/canvas-apps/references/ValidationWorkflow.md

@@ -161,8 +161,9 @@ diagnostic history, and a fresh agent would have to rediscover all of it.
 - The only sanctioned re-delegation is back to `canvas-app-planner` when a builder
   returned `Status: Blocked` because its brief was genuinely missing a definition or an
   assignment field — never for a diagnostic on a file that already exists.
-
-Never modify `[working directory]/_EditorState.pa.yaml` while repairing diagnostics.
+- Modify `[working directory]/_EditorState.pa.yaml` when a diagnostic identifies it or when the requested
+  screen or component-definition order requires correction. Preserve valid names and
+  repair only the affected order entries.
 
 ### Verify before you summarize