cox-protocol-package 1.0.2 → 1.2.0

package/cox_protocol/starter/README.md

@@ -0,0 +1,7 @@
+# COX example
+
+This starter specifies an intended interface. Its SVG is an illustration, not evidence of a shipped product.
+
+Run `cox validate .`, then `cox compile . --target all`. React output is structural scaffolding: supply actual styles, behavior and tests in the consuming app.
+
+Change `EvidenceSummary.Intended` to an unknown level such as `Certain` to see a schema diagnostic; restore it and revalidate. `cox verify-package build/package/<project-slug>.zip` checks the archived file inventory.

package/cox_protocol/starter/manifest.cox

@@ -0,0 +1,26 @@
+CoxVersion: '1.0'
+FileType: manifest
+Slug: cox_example
+Schema: cox.manifest.v1
+ProjectName: CoxExample
+PackageName: cox_example.zip
+ProtocolExtension: .cox
+MimeType: application/vnd.cox+yaml
+EntryPoint: manifest.cox
+ReferenceDocs:
+- README.md
+Pages:
+- PageName: Example
+  Slug: example
+  Folder: page
+  PageInstruction: page/page.cox
+  PageScreenshotPlaceholder: page/reference.svg
+  Components:
+  - Slug: action_button
+    Folder: page/action_button
+    ComponentInstruction: page/action_button/action_button.cox
+    ComponentScreenshotPlaceholder: page/action_button/reference.svg
+BuildTargets:
+- json
+- react
+- package

package/cox_protocol/starter/page/action_button/action_button.cox

@@ -0,0 +1,34 @@
+CoxVersion: '1.0'
+FileType: component_spec
+Slug: action_button
+Schema: cox.component.v1
+ComponentName: ActionButton
+Role: Primary action
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended:
+  - Reference illustration describes a proposed interface, not an observed deployed
+    product.
+  Recommended: []
+VisibleStructure:
+  Label: Continue
+Interactions:
+  Intended:
+  - Activate using pointer, Enter or Space.
+  Recommended:
+  - Preserve a visible keyboard focus indicator.
+NamingDecision:
+  ChosenName: action_button
+  Reason: Explicit role in the example brief.
+  RejectedAlternatives: []
+  AmbiguityRisk: Low
+  EvidenceLevel: Intended
+VisualStyle:
+  Tokens:
+  - color.action
+  - space.control
+ImplementationHints:
+- Implement the action only after its behavior is supplied; the compiler emits a structural
+  scaffold.

package/cox_protocol/starter/page/action_button/reference.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240"><rect width="480" height="240" fill="#f8fafc"/><text x="32" y="48" font-family="sans-serif" font-size="18" fill="#0f172a">COX example: intended interface</text><rect x="32" y="92" width="144" height="48" rx="8" fill="#1d4ed8"/><text x="68" y="122" font-family="sans-serif" font-size="16" fill="white">Continue</text><text x="32" y="192" font-family="sans-serif" font-size="12" fill="#475569">Reference illustration; not a product screenshot.</text></svg>

package/cox_protocol/starter/page/page.cox

@@ -0,0 +1,39 @@
+CoxVersion: '1.0'
+FileType: page_spec
+Slug: example
+Schema: cox.page.v1
+PageName: Example
+ProjectName: CoxExample
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended:
+  - Reference illustration describes a proposed interface, not an observed deployed
+    product.
+  Recommended: []
+VisibleStructure:
+  Regions:
+  - primary_action
+Interactions:
+  Intended:
+  - User reviews the proposed action before invoking it.
+NamingDecision:
+  ChosenName: Example
+  Reason: Explicit role in the example brief.
+  RejectedAlternatives: []
+  AmbiguityRisk: Low
+  EvidenceLevel: Intended
+Layout:
+  Desktop: One centered content column.
+  Tablet: One centered content column.
+  Mobile: One column with comfortable page padding.
+Children:
+  Components:
+  - Slug: action_button
+    Folder: action_button/
+    Role: Primary action
+RecursiveDecompositionDecision:
+  Complexity: SimplePage
+  Reason: One reusable action.
+  Action: Bind the action_button component.

package/cox_protocol/starter/page/reference.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240"><rect width="480" height="240" fill="#f8fafc"/><text x="32" y="48" font-family="sans-serif" font-size="18" fill="#0f172a">COX example: intended interface</text><rect x="32" y="92" width="144" height="48" rx="8" fill="#1d4ed8"/><text x="68" y="122" font-family="sans-serif" font-size="16" fill="white">Continue</text><text x="32" y="192" font-family="sans-serif" font-size="12" fill="#475569">Reference illustration; not a product screenshot.</text></svg>

package/editor-support/vscode/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.2.0
+
+- Align release versions with the compiler and validate complete document snippets against canonical schemas.
+- Include UserSpecified interaction evidence in authoring snippets.
+- Use the locked repository packaging toolchain.
+
 ## 1.1.0
 
 - Added installable extension metadata for COX Language Support

package/editor-support/vscode/README.md

@@ -24,7 +24,8 @@ COX Language Support adds syntax highlighting, editor configuration, and authori
 Create a local VSIX package from this folder:
 
 ```bash
-vsce package --out ../../build/vscode/cox-language-support-1.1.0.vsix
+npm ci --prefix ../..
+npm run package
 ```
 
 ## Notes

package/editor-support/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "cox-language-support",
   "displayName": "COX Language Support",
   "description": "Syntax highlighting, snippets, and packaging support for COX files.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "publisher": "charbelmalo",
   "license": "MIT",
   "preview": true,
@@ -31,7 +31,7 @@
     "agent-readable"
   ],
   "scripts": {
-    "package": "vsce package --out ../../build/vscode/cox-language-support-1.1.0.vsix"
+    "package": "node ../../scripts/package-vscode.mjs"
   },
   "contributes": {
     "languages": [
@@ -87,4 +87,4 @@
       }
     }
   }
-}
+}

package/editor-support/vscode/snippets/cox-common.json

@@ -9,4 +9,4 @@
     ],
     "description": "Insert the common COX v1.0 document header"
   }
-}
+}

package/editor-support/vscode/snippets/cox-component.json

@@ -26,6 +26,7 @@
       "  Tokens: []",
       "Interactions:",
       "  Visible: []",
+      "  UserSpecified: []",
       "  Inferred: []",
       "  Intended: []",
       "  Recommended: []",
@@ -38,4 +39,4 @@
     ],
     "description": "Insert a COX component specification skeleton"
   }
-}
+}

package/editor-support/vscode/snippets/cox-crop-metadata.json

@@ -20,4 +20,4 @@
     ],
     "description": "Insert a COX crop metadata skeleton"
   }
-}
+}

package/editor-support/vscode/snippets/cox-manifest.json

@@ -36,4 +36,4 @@
     ],
     "description": "Insert a COX manifest skeleton"
   }
-}
+}

package/editor-support/vscode/snippets/cox-page.json

@@ -31,6 +31,7 @@
       "  Components: []",
       "Interactions:",
       "  Visible: []",
+      "  UserSpecified: []",
       "  Inferred: []",
       "  Intended: []",
       "  Recommended: []",
@@ -41,4 +42,4 @@
     ],
     "description": "Insert a COX page specification skeleton"
   }
-}
+}

package/editor-support/vscode/snippets/cox-protocol.json

@@ -13,4 +13,4 @@
     ],
     "description": "Insert a COX protocol document skeleton"
   }
-}
+}

package/examples/quickstart/README.md

@@ -0,0 +1,7 @@
+# COX example
+
+This starter specifies an intended interface. Its SVG is an illustration, not evidence of a shipped product.
+
+Run `cox validate .`, then `cox compile . --target all`. React output is structural scaffolding: supply actual styles, behavior and tests in the consuming app.
+
+Change `EvidenceSummary.Intended` to an unknown level such as `Certain` to see a schema diagnostic; restore it and revalidate. `cox verify-package build/package/<project-slug>.zip` checks the archived file inventory.

package/examples/quickstart/manifest.cox

@@ -0,0 +1,26 @@
+CoxVersion: '1.0'
+FileType: manifest
+Slug: cox_example
+Schema: cox.manifest.v1
+ProjectName: CoxExample
+PackageName: cox_example.zip
+ProtocolExtension: .cox
+MimeType: application/vnd.cox+yaml
+EntryPoint: manifest.cox
+ReferenceDocs:
+- README.md
+Pages:
+- PageName: Example
+  Slug: example
+  Folder: page
+  PageInstruction: page/page.cox
+  PageScreenshotPlaceholder: page/reference.svg
+  Components:
+  - Slug: action_button
+    Folder: page/action_button
+    ComponentInstruction: page/action_button/action_button.cox
+    ComponentScreenshotPlaceholder: page/action_button/reference.svg
+BuildTargets:
+- json
+- react
+- package

package/examples/quickstart/page/action_button/action_button.cox

@@ -0,0 +1,34 @@
+CoxVersion: '1.0'
+FileType: component_spec
+Slug: action_button
+Schema: cox.component.v1
+ComponentName: ActionButton
+Role: Primary action
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended:
+  - Reference illustration describes a proposed interface, not an observed deployed
+    product.
+  Recommended: []
+VisibleStructure:
+  Label: Continue
+Interactions:
+  Intended:
+  - Activate using pointer, Enter or Space.
+  Recommended:
+  - Preserve a visible keyboard focus indicator.
+NamingDecision:
+  ChosenName: action_button
+  Reason: Explicit role in the example brief.
+  RejectedAlternatives: []
+  AmbiguityRisk: Low
+  EvidenceLevel: Intended
+VisualStyle:
+  Tokens:
+  - color.action
+  - space.control
+ImplementationHints:
+- Implement the action only after its behavior is supplied; the compiler emits a structural
+  scaffold.

package/examples/quickstart/page/action_button/reference.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240"><rect width="480" height="240" fill="#f8fafc"/><text x="32" y="48" font-family="sans-serif" font-size="18" fill="#0f172a">COX example: intended interface</text><rect x="32" y="92" width="144" height="48" rx="8" fill="#1d4ed8"/><text x="68" y="122" font-family="sans-serif" font-size="16" fill="white">Continue</text><text x="32" y="192" font-family="sans-serif" font-size="12" fill="#475569">Reference illustration; not a product screenshot.</text></svg>

package/examples/quickstart/page/page.cox

@@ -0,0 +1,39 @@
+CoxVersion: '1.0'
+FileType: page_spec
+Slug: example
+Schema: cox.page.v1
+PageName: Example
+ProjectName: CoxExample
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended:
+  - Reference illustration describes a proposed interface, not an observed deployed
+    product.
+  Recommended: []
+VisibleStructure:
+  Regions:
+  - primary_action
+Interactions:
+  Intended:
+  - User reviews the proposed action before invoking it.
+NamingDecision:
+  ChosenName: Example
+  Reason: Explicit role in the example brief.
+  RejectedAlternatives: []
+  AmbiguityRisk: Low
+  EvidenceLevel: Intended
+Layout:
+  Desktop: One centered content column.
+  Tablet: One centered content column.
+  Mobile: One column with comfortable page padding.
+Children:
+  Components:
+  - Slug: action_button
+    Folder: action_button/
+    Role: Primary action
+RecursiveDecompositionDecision:
+  Complexity: SimplePage
+  Reason: One reusable action.
+  Action: Bind the action_button component.

package/examples/quickstart/page/reference.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240"><rect width="480" height="240" fill="#f8fafc"/><text x="32" y="48" font-family="sans-serif" font-size="18" fill="#0f172a">COX example: intended interface</text><rect x="32" y="92" width="144" height="48" rx="8" fill="#1d4ed8"/><text x="68" y="122" font-family="sans-serif" font-size="16" fill="white">Continue</text><text x="32" y="192" font-family="sans-serif" font-size="12" fill="#475569">Reference illustration; not a product screenshot.</text></svg>

package/guides/contract-demo.md

@@ -0,0 +1,24 @@
+# Contract → diagnostic → correction → artifact
+
+The reproducible demonstration uses a manifest, one page and one action component. It establishes identity and evidence handling in the implemented COX compiler.
+
+After installing the project, run from the source checkout:
+
+```bash
+python scripts/demo.py --out /tmp/cox-contract-demo
+```
+
+The directory must be new or empty. The script creates the starter, temporarily changes the component's `Slug` from `action_button` to `action_buton`, captures the actual `BINDING_MISMATCH` error, restores the correct value, validates three documents, compiles all targets into an external directory and verifies the ZIP inventory.
+
+Read these artifacts in order:
+
+1. `01-invalid-component.cox.txt`: the broken contract.
+2. `02-diagnostic.json`: the real validator output, including file and field.
+3. `03-corrected-component.cox.txt`: the single-field correction.
+4. `04-result.json`: observed result and capability scope.
+5. `build/react/`: typed scaffolding that retains evidence and intended behavior as comments.
+6. `build/package/`: source/artifact ZIP and SHA-256 inventory.
+
+The reference SVGs are illustrations of a proposed layout. They are not screenshots of a deployed application. The generated React uses structural `<main>` and `<section>` elements; an implementer supplies the real controls, styling and behavior.
+
+This example checks a design-contract binding. It does not inspect rendered UI, evaluate an application's AST, or prove that the intended keyboard interaction has been implemented. A portfolio case study can show the concrete failure/recovery loop and explain these boundaries.