// @bun
var G=Object.defineProperty;var H=(B)=>B;function J(B,D){this[B]=H.bind(null,D)}var M=(B,D)=>{for(var F in D)G(B,F,{get:D[F],enumerable:!0,configurable:!0,set:J.bind(D,F)})};var N=(B,D)=>()=>(B&&(D=B(B=0)),D);import E from"@contractspec/lib.ui-link";import{ChevronRight as K}from"lucide-react";import{jsx as q,jsxs as A}from"react/jsx-runtime";function V(){return A("div",{className:"space-y-8",children:[A("div",{className:"space-y-4",children:[q("h1",{className:"font-bold text-4xl",children:"Overlays"}),A("p",{className:"text-muted-foreground",children:["An ",q("strong",{children:"OverlaySpec"})," allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."]})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Why overlays matter"}),q("p",{className:"text-muted-foreground",children:"Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."}),q("p",{className:"text-muted-foreground",children:"Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"What overlays can do"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[A("li",{children:[q("strong",{children:"Hide or show fields"})," \u2013 Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"]}),A("li",{children:[q("strong",{children:"Reorder fields"})," \u2013 Change the order in which fields appear"]}),A("li",{children:[q("strong",{children:"Rename labels"})," \u2013 Use different terminology that's more familiar to the user"]}),A("li",{children:[q("strong",{children:"Change layouts"})," \u2013 Switch between list, grid, or card views"]}),A("li",{children:[q("strong",{children:"Add help text"})," \u2013 Provide context-specific guidance"]}),A("li",{children:[q("strong",{children:"Set default values"})," \u2013 Pre-fill forms with tenant-specific defaults"]}),A("li",{children:[q("strong",{children:"Apply branding"})," \u2013 Customize colors, logos, and styling (within approved themes)"]})]})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Example OverlaySpec"}),q("p",{className:"text-muted-foreground",children:"Here's an overlay that customizes an order form:"}),q("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:q("pre",{children:`overlayId: acme-order-form
version: '1.0.0'.0.0
appliesTo:
  capability: createOrder
  tenantId: acme-corp
  
modifications:
  - type: hideField
    field: internalNotes
    reason: "ACME doesn't use internal notes"
    
  - type: renameLabel
    field: customerReference
    newLabel: "PO Number"
    
  - type: reorderFields
    fields:
      - customerReference
      - items
      - shippingAddress
      - billingAddress
      - paymentMethod
      
  - type: setDefault
    field: paymentMethod
    value: "net30"
    
  - type: addHelpText
    field: customerReference
    text: "Enter your purchase order number from your procurement system"
    
  - type: makeRequired
    field: customerReference
    
signature:
  algorithm: EdDSA
  publicKey: "acme-corp-overlay-key"
  signature: "base64-encoded-signature"`})})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Safety guarantees"}),q("p",{className:"text-muted-foreground",children:"Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[A("li",{children:[q("strong",{children:"Overlays cannot grant new permissions"})," \u2013 They can only hide or rearrange what the user is already allowed to see"]}),A("li",{children:[q("strong",{children:"Overlays cannot bypass validation"})," \u2013 Field types, constraints, and business rules from the underlying spec still apply"]}),A("li",{children:[q("strong",{children:"Overlays must be signed"})," \u2013 Only authorized parties (typically tenant admins) can create overlays"]}),A("li",{children:[q("strong",{children:"Overlays are versioned"})," \u2013 Changes to overlays are tracked and can be rolled back"]}),A("li",{children:[q("strong",{children:"Overlays are audited"})," \u2013 Every overlay application is logged"]})]})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Creating overlays"}),q("p",{className:"text-muted-foreground",children:"Overlays can be created through:"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[A("li",{children:[q("strong",{children:"Visual editor"})," \u2013 A drag-and-drop interface for non-technical users"]}),A("li",{children:[q("strong",{children:"TypeScript/JSON"})," \u2013 For developers who prefer code"]}),A("li",{children:[q("strong",{children:"API"})," \u2013 Programmatically create overlays for automation"]})]}),q("p",{className:"text-muted-foreground",children:"Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."}),A("p",{className:"text-muted-foreground",children:["See"," ",q(E,{href:"/docs/libraries/overlay-engine",className:"text-violet-400 underline",children:"Overlay Engine docs"})," ","and the"," ",q(E,{href:"/docs/advanced/overlay-editor",className:"text-violet-400 underline",children:"Overlay Editor guide"})," ","for end-to-end workflows."]})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Overlay scope"}),q("p",{className:"text-muted-foreground",children:"Overlays can be scoped to:"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[A("li",{children:[q("strong",{children:"Tenant"})," \u2013 All users in a tenant see the same overlay"]}),A("li",{children:[q("strong",{children:"User"})," \u2013 Individual users can have personal overlays"]}),A("li",{children:[q("strong",{children:"Role"})," \u2013 All users with a specific role see the overlay"]}),A("li",{children:[q("strong",{children:"Device"})," \u2013 Different overlays for mobile vs desktop"]})]}),q("p",{className:"text-muted-foreground",children:"If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Best practices"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[q("li",{children:"Start with the default UI and only create overlays when users request specific changes."}),q("li",{children:"Document why each overlay modification was made\u2014this helps when reviewing or updating overlays."}),q("li",{children:"Test overlays thoroughly to ensure they don't break workflows or confuse users."}),q("li",{children:"Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences."}),q("li",{children:"Regularly review overlays to remove ones that are no longer needed."}),q("li",{children:"Protect overlay signing keys carefully\u2014they control what customizations are allowed."})]})]}),A("div",{className:"space-y-4",children:[q("h2",{className:"font-bold text-2xl",children:"Where overlays fit in the runtime"}),q("p",{className:"text-muted-foreground",children:"Overlays are safest when they sit on top of a declared bundle surface instead of ad hoc page code. Use the module-bundles docs first, then apply overlays as auditable customization on top of the resolved surface plan."}),A("div",{className:"flex flex-wrap gap-3",children:[q(E,{href:"/docs/specs/module-bundles",className:"btn-primary",children:"Module bundles"}),q(E,{href:"/docs/guides/first-module-bundle",className:"btn-ghost",children:"Build a first module bundle"})]})]}),A("div",{className:"flex items-center gap-4 pt-4",children:[q(E,{href:"/docs/specs/policy",className:"btn-ghost",children:"Previous: Policy"}),A(E,{href:"/docs/safety",className:"btn-primary",children:["Next: Safety ",q(K,{size:16})]})]})]})}export{V as SpecsOverlaysPage};
