{ "schemaVersion": 1, "contractVersion": "1.1.0", "product": "Raycast public design reference", "authorship": "local reconstructed contract", "claim": "Authoritative only for this static reference package; it is not a Raycast service, private API, or native SDK contract.", "generatedAt": "2026-09-18T22:45:23.563742Z", "scope": "public-evidence", "dataSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "urn:panout:raycast:public-reference:1", "title": "Local Raycast reference data", "description": "Strict authoring records. Cross-record invariants and safe navigation policy also apply.", "$defs": { "Id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "UtcTimestamp": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "LocalHref": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(?:[a-z0-9][a-z0-9-]*\\.html(?:\\?[^#\\s]*)?(?:#[a-z][a-z0-9-]*)?|#[a-z][a-z0-9-]*)$" }, "OfficialPublicHref": { "type": "string", "minLength": 8, "maxLength": 600, "format": "uri", "pattern": "^https://(?:www\\.)?raycast\\.com(?:/[^\\s]*)?$" }, "Person": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "handle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, { "type": "null" } ] } }, "required": [ "displayName", "handle" ] }, "Command": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 140 }, "subtitle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] } }, "required": [ "id", "title", "subtitle" ] }, "Attachment": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^/\\\\\\x00-\\x1F]+$" }, "byteLength": { "type": "integer", "minimum": 0, "maximum": 20971520 }, "mediaType": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name", "byteLength", "mediaType" ] }, "ArticleBlock": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "paragraph", "heading", "code", "caption" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "language": { "anyOf": [ { "type": "string", "enum": [ "text", "bash", "javascript", "typescript", "json" ] }, { "type": "null" } ] } }, "required": [ "kind", "text", "language" ] }, "Extension": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "slug": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "summary": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 400 }, { "type": "null" } ] }, "publisher": { "anyOf": [ { "$ref": "#/$defs/Person" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "productivity", "developer-tools", "communication", "design", "utilities" ] }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "macos", "windows" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true }, "iconAssetId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, { "type": "null" } ] }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" }, "commands": { "type": "array", "items": { "$ref": "#/$defs/Command" }, "minItems": 0, "maxItems": 60 }, "access": { "type": "string", "enum": [ "public", "sign-in-required", "unavailable" ] }, "updatedAt": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "locale": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 }, "minItems": 0, "maxItems": 10, "uniqueItems": true }, "downloadCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "id", "slug", "name", "summary", "publisher", "category", "platforms", "iconAssetId", "publicUrl", "commands", "access", "updatedAt", "locale", "tags", "downloadCount", "revision" ] }, "Plan": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 400 }, "audience": { "type": "string", "enum": [ "individual", "team", "enterprise" ] }, "pricingMode": { "type": "string", "enum": [ "free", "fixed", "contact" ] }, "currency": { "const": "USD" }, "monthlyUsdCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "annualMonthlyUsdCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "featureIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "minItems": 0, "maxItems": 50, "uniqueItems": true }, "ctaLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "ctaHref": { "anyOf": [ { "$ref": "#/$defs/OfficialPublicHref" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "name", "description", "audience", "pricingMode", "currency", "monthlyUsdCents", "annualMonthlyUsdCents", "featureIds", "ctaLabel", "ctaHref", "updatedAt", "revision" ] }, "Article": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "slug": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "kind": { "type": "string", "enum": [ "article", "resource", "changelog" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "summary": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 600 }, { "type": "null" } ] }, "author": { "anyOf": [ { "$ref": "#/$defs/Person" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "category": { "type": "string", "enum": [ "guide", "engineering", "news", "release" ] }, "locale": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "coverAssetId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, { "type": "null" } ] }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" }, "blocks": { "type": "array", "items": { "$ref": "#/$defs/ArticleBlock" }, "minItems": 1, "maxItems": 80 }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "slug", "kind", "title", "summary", "author", "publishedAt", "updatedAt", "category", "locale", "coverAssetId", "publicUrl", "blocks", "revision" ] }, "Feature": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "summary": { "type": "string", "minLength": 1, "maxLength": 600 }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "macos", "windows", "ios", "browser" ] }, "minItems": 1, "maxItems": 4, "uniqueItems": true }, "entitlementLabel": { "type": "string", "enum": [ "free", "pro", "teams", "unverified" ] }, "availabilityLabel": { "type": "string", "minLength": 1, "maxLength": 100 }, "mediaAssetId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, { "type": "null" } ] }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" }, "relatedFeatureIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "minItems": 0, "maxItems": 12, "uniqueItems": true }, "updatedAt": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "title", "summary", "platforms", "entitlementLabel", "availabilityLabel", "mediaAssetId", "publicUrl", "relatedFeatureIds", "updatedAt", "revision" ] }, "PublicFeedback": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "category": { "type": "string", "enum": [ "feature-request", "bug-report", "billing-issue", "ios", "other" ] }, "senderEmail": { "type": "string", "minLength": 3, "maxLength": 254, "format": "email", "pattern": "^[^\\s@]+@example\\.com$" }, "appVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/Attachment" }, "minItems": 0, "maxItems": 5 }, "submissionState": { "type": "string", "enum": [ "draft", "validating", "success", "error", "offline" ] }, "createdAt": { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "bugType": { "anyOf": [ { "type": "string", "enum": [ "not_working", "crashing", "freezing" ] }, { "type": "null" } ] }, "feature": { "anyOf": [ { "type": "string", "enum": [ "AI", "Applications", "Auto Quit", "Calculator", "Calendar/My Schedule", "Clipboard History", "Cloud Sync", "Custom Themes", "Deeplinks", "Dictation", "Extensions", "Flight Tracker", "Focus", "Hyper Key", "Notes", "Quicklinks", "Script Commands", "Search Files", "Settings", "Snippets", "Store", "Window Management", "Other" ] }, { "type": "null" } ] } }, "required": [ "id", "category", "senderEmail", "appVersion", "message", "attachments", "submissionState", "createdAt", "bugType", "feature" ] }, "Asset": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "kind": { "type": "string", "enum": [ "icon", "logo", "font", "screenshot", "photo", "illustration", "video" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "image/avif", "font/woff2", "video/mp4", "video/webm" ] }, "localPath": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^assets/(?:[a-zA-Z0-9_-]+/)*[a-zA-Z0-9_-]+\\.(?:svg|png|jpg|jpeg|webp|avif|woff2|mp4|webm)$" }, "sourceUrl": { "type": "string", "minLength": 8, "maxLength": 600, "format": "uri", "pattern": "^https://[^\\s]+$" }, "widthPx": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 20000 }, { "type": "null" } ] }, "heightPx": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 20000 }, { "type": "null" } ] }, "byteLength": { "type": "integer", "minimum": 1, "maximum": 104857600 }, "sha256": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$" }, "alt": { "type": "string", "minLength": 0, "maxLength": 400 }, "decorative": { "type": "boolean" }, "theme": { "type": "string", "enum": [ "dark", "light", "any" ] }, "loading": { "type": "string", "enum": [ "eager", "lazy" ] }, "rights": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "package-license", "open-font-license", "private-reference-only", "original" ] }, "notice": { "type": "string", "minLength": 1, "maxLength": 600 }, "distribution": { "type": "string", "enum": [ "private-reference-only", "license-conditions", "original" ] } }, "required": [ "status", "notice", "distribution" ] } }, "required": [ "id", "kind", "mimeType", "localPath", "sourceUrl", "widthPx", "heightPx", "byteLength", "sha256", "alt", "decorative", "theme", "loading", "rights" ] }, "CollectionEnvelope": { "type": "object", "additionalProperties": false, "properties": { "schemaVersion": { "const": 1 }, "requestId": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "loading", "ready", "empty", "partial", "stale", "error", "offline", "permission" ] }, "items": { "type": "array", "items": { "$ref": "#/$defs/Extension" }, "minItems": 0, "maxItems": 500 }, "receivedAt": { "anyOf": [ { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "minLength": 20, "maxLength": 30, "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, { "type": "null" } ] }, "hasMore": { "const": false }, "message": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 400 }, { "type": "null" } ] } }, "required": [ "schemaVersion", "requestId", "state", "items", "receivedAt", "expiresAt", "hasMore", "message" ] }, "ExternalPublicHref": { "type": "string", "minLength": 9, "maxLength": 2048, "format": "uri", "pattern": "^https://(?:www\\.)?(?:raycast\\.com|github\\.com|manual\\.raycast\\.com|developers\\.raycast\\.com|jobs\\.ashbyhq\\.com|example\\.com|keychron\\.com|chromewebstore\\.google\\.com|apps\\.apple\\.com|microsoft\\.com)/[^\\s\\x00-\\x1f<>]*$" }, "Publisher": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "handle": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 600 }, { "type": "null" } ] }, "avatarAssetId": { "anyOf": [ { "$ref": "#/$defs/Id" }, { "type": "null" } ] }, "joinedAt": { "anyOf": [ { "$ref": "#/$defs/UtcTimestamp" }, { "type": "null" } ] }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" }, "extensionIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 0, "maxItems": 200 }, "website": { "anyOf": [ { "$ref": "#/$defs/ExternalPublicHref" }, { "type": "null" } ] }, "access": { "type": "string", "enum": [ "public", "unavailable" ] } }, "required": [ "id", "updatedAt", "revision", "handle", "name", "description", "avatarAssetId", "joinedAt", "publicUrl", "extensionIds", "website", "access" ] }, "CapabilityRating": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "enum": [ "intelligence", "speed", "context", "vision", "tools" ] }, "value": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 5 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 240 } }, "required": [ "name", "value", "description" ] }, "AIModel": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "provider": { "type": "string", "minLength": 1, "maxLength": 100 }, "providerAssetId": { "anyOf": [ { "$ref": "#/$defs/Id" }, { "type": "null" } ] }, "contextTokens": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000000 }, { "type": "null" } ] }, "ratings": { "type": "array", "items": { "$ref": "#/$defs/CapabilityRating" }, "minItems": 1, "maxItems": 5 }, "planIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 1, "maxItems": 8 }, "status": { "type": "string", "enum": [ "available", "preview", "retired", "unverified" ] }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "name", "provider", "providerAssetId", "contextTokens", "ratings", "planIds", "status", "publicUrl" ] }, "ToolCall": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "icon": { "type": "string", "minLength": 1, "maxLength": 40 }, "status": { "type": "string", "enum": [ "queued", "running", "complete", "error", "blocked" ] }, "inputSummary": { "type": "string", "minLength": 1, "maxLength": 400 }, "outputSummary": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1200 }, { "type": "null" } ] }, "sourceHref": { "anyOf": [ { "$ref": "#/$defs/ExternalPublicHref" }, { "type": "null" } ] } }, "required": [ "id", "name", "icon", "status", "inputSummary", "outputSummary", "sourceHref" ] }, "ToolGroup": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "label": { "type": "string", "minLength": 1, "maxLength": 180 }, "calls": { "type": "array", "items": { "$ref": "#/$defs/ToolCall" }, "minItems": 1, "maxItems": 20 }, "defaultExpanded": { "type": "boolean" } }, "required": [ "id", "label", "calls", "defaultExpanded" ] }, "TaskMessage": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "toolGroups": { "type": "array", "items": { "$ref": "#/$defs/ToolGroup" }, "minItems": 0, "maxItems": 12 } }, "required": [ "id", "role", "text", "toolGroups" ] }, "ScriptedTask": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "project": { "type": "string", "minLength": 1, "maxLength": 100 }, "scenario": { "type": "string", "enum": [ "research", "planning", "writing", "automation" ] }, "messages": { "type": "array", "items": { "$ref": "#/$defs/TaskMessage" }, "minItems": 1, "maxItems": 40 }, "composerPlaceholder": { "type": "string", "minLength": 1, "maxLength": 180 }, "status": { "type": "string", "enum": [ "ready", "loading", "error", "offline", "permission" ] }, "sourceUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "title", "project", "scenario", "messages", "composerPlaceholder", "status", "sourceUrl" ] }, "ReleaseSection": { "type": "object", "additionalProperties": false, "properties": { "heading": { "type": "string", "enum": [ "New", "Improved", "Fixed", "Known limitations" ] }, "items": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "minItems": 1, "maxItems": 80 } }, "required": [ "heading", "items" ] }, "Release": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "version": { "type": "string", "minLength": 1, "maxLength": 40 }, "platform": { "type": "string", "enum": [ "macos", "windows", "ios" ] }, "publishedAt": { "$ref": "#/$defs/UtcTimestamp" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "summary": { "type": "string", "minLength": 1, "maxLength": 600 }, "sections": { "type": "array", "items": { "$ref": "#/$defs/ReleaseSection" }, "minItems": 1, "maxItems": 4 }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "version", "platform", "publishedAt", "title", "summary", "sections", "publicUrl" ] }, "Story": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "kind": { "type": "string", "enum": [ "community", "customer" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "summary": { "type": "string", "minLength": 1, "maxLength": 600 }, "person": { "$ref": "#/$defs/Person" }, "company": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 140 }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 140 }, { "type": "null" } ] }, "portraitAssetId": { "anyOf": [ { "$ref": "#/$defs/Id" }, { "type": "null" } ] }, "companyAssetId": { "anyOf": [ { "$ref": "#/$defs/Id" }, { "type": "null" } ] }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 600 }, { "type": "null" } ] }, "body": { "type": "array", "items": { "$ref": "#/$defs/ArticleBlock" }, "minItems": 1, "maxItems": 60 }, "relatedExtensionIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 0, "maxItems": 20 }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "kind", "title", "summary", "person", "company", "role", "portraitAssetId", "companyAssetId", "quote", "body", "relatedExtensionIds", "publicUrl" ] }, "ExtensionTemplate": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "summary": { "type": "string", "minLength": 1, "maxLength": 600 }, "instructionsDescription": { "type": "string", "minLength": 1, "maxLength": 600 }, "about": { "type": "array", "items": { "$ref": "#/$defs/RichText" }, "minItems": 1, "maxItems": 8 }, "publisherId": { "$ref": "#/$defs/Id" }, "prerequisites": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "minItems": 1, "maxItems": 8 }, "screenshotAssetIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 0, "maxItems": 12 }, "repositoryHref": { "$ref": "#/$defs/ExternalPublicHref" }, "installCommand": { "type": "string", "minLength": 1, "maxLength": 500 }, "organizationRequired": { "const": true }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "name", "summary", "instructionsDescription", "about", "publisherId", "prerequisites", "screenshotAssetIds", "repositoryHref", "installCommand", "organizationRequired", "publicUrl" ] }, "AccountEntryAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "intent": { "type": "string", "enum": [ "sign-in", "sign-up", "organization", "confirm" ] }, "mode": { "type": "string", "enum": [ "email", "password", "provider" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "apple", "github", "google" ] }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^[^\\s@]+@example\\.com$" }, { "type": "null" } ] }, "passwordPresent": { "type": "boolean" }, "state": { "type": "string", "enum": [ "idle", "invalid", "ready-for-handoff", "missing-confirmation-token", "unavailable" ] }, "returnPath": { "$ref": "#/$defs/LocalHref" }, "createdAt": { "$ref": "#/$defs/UtcTimestamp" } }, "required": [ "id", "intent", "mode", "provider", "email", "passwordPresent", "state", "returnPath", "createdAt" ] }, "JobOpening": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "department": { "type": "string", "enum": [ "engineering", "design", "operations", "marketing" ] }, "location": { "type": "string", "minLength": 1, "maxLength": 140 }, "employment": { "type": "string", "enum": [ "full-time", "part-time", "contract" ] }, "remote": { "type": "boolean" }, "applicationHref": { "$ref": "#/$defs/ExternalPublicHref" }, "status": { "type": "string", "enum": [ "open", "closed", "unverified" ] } }, "required": [ "id", "updatedAt", "revision", "title", "department", "location", "employment", "remote", "applicationHref", "status" ] }, "ProductSpecification": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 240 } }, "required": [ "label", "value" ] }, "KeyboardProduct": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "updatedAt": { "$ref": "#/$defs/UtcTimestamp" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string", "minLength": 1, "maxLength": 140 }, "availability": { "type": "string", "enum": [ "available", "sold-out", "waitlist", "unverified" ] }, "specifications": { "type": "array", "items": { "$ref": "#/$defs/ProductSpecification" }, "minItems": 1, "maxItems": 40 }, "imageAssetIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 0, "maxItems": 20 }, "audioAssetId": { "anyOf": [ { "$ref": "#/$defs/Id" }, { "type": "null" } ] }, "audioTranscript": { "type": "string", "minLength": 1, "maxLength": 1200 }, "vendorHref": { "$ref": "#/$defs/ExternalPublicHref" }, "publicUrl": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "updatedAt", "revision", "name", "availability", "specifications", "imageAssetIds", "audioAssetId", "audioTranscript", "vendorHref", "publicUrl" ] }, "ExtensionVersion": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "extensionId": { "$ref": "#/$defs/Id" }, "version": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publishedAt": { "$ref": "#/$defs/UtcTimestamp" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "noteFormat": { "type": "string", "enum": [ "bullets", "paragraph", "none" ] }, "notes": { "type": "array", "items": { "$ref": "#/$defs/RichText" }, "minItems": 0, "maxItems": 20 } }, "required": [ "id", "extensionId", "version", "publishedAt", "title", "noteFormat", "notes" ] }, "ExtensionDetail": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/Id" }, "extensionId": { "$ref": "#/$defs/Id" }, "publisherId": { "$ref": "#/$defs/Id" }, "summary": { "type": "string", "minLength": 1, "maxLength": 600 }, "readmeBlocks": { "type": "array", "items": { "$ref": "#/$defs/ArticleBlock" }, "minItems": 1, "maxItems": 80 }, "screenshotAssetIds": { "type": "array", "items": { "$ref": "#/$defs/Id" }, "minItems": 0, "maxItems": 20 }, "commands": { "type": "array", "items": { "$ref": "#/$defs/Command" }, "minItems": 0, "maxItems": 100 }, "versions": { "type": "array", "items": { "$ref": "#/$defs/ExtensionVersion" }, "minItems": 0, "maxItems": 200 }, "contributors": { "type": "array", "items": { "$ref": "#/$defs/Person" }, "minItems": 0, "maxItems": 40 }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "macos", "windows" ] }, "minItems": 1, "maxItems": 2 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 0, "maxItems": 12 }, "sourceHref": { "$ref": "#/$defs/ExternalPublicHref" }, "installHref": { "$ref": "#/$defs/OfficialPublicHref" } }, "required": [ "id", "extensionId", "publisherId", "summary", "readmeBlocks", "screenshotAssetIds", "commands", "versions", "contributors", "platforms", "categories", "sourceHref", "installHref" ] }, "DraftAttachment": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[^\\x00]+$" }, "byteLength": { "type": "integer", "minimum": 0, "maximum": 20971520 }, "mediaType": { "type": "string", "minLength": 0, "maxLength": 255 } }, "required": [ "name", "byteLength", "mediaType" ] }, "FeedbackDraft": { "type": "object", "additionalProperties": false, "properties": { "category": { "type": "string", "enum": [ "feature-request", "bug-report", "billing-issue", "ios", "other" ] }, "senderEmail": { "type": "string", "minLength": 3, "maxLength": 254, "format": "email" }, "appVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/DraftAttachment" }, "minItems": 0, "maxItems": 5 }, "bugType": { "anyOf": [ { "type": "string", "enum": [ "not_working", "crashing", "freezing" ] }, { "type": "null" } ] }, "feature": { "anyOf": [ { "type": "string", "enum": [ "AI", "Applications", "Auto Quit", "Calculator", "Calendar/My Schedule", "Clipboard History", "Cloud Sync", "Custom Themes", "Deeplinks", "Dictation", "Extensions", "Flight Tracker", "Focus", "Hyper Key", "Notes", "Quicklinks", "Script Commands", "Search Files", "Settings", "Snippets", "Store", "Window Management", "Other" ] }, { "type": "null" } ] } }, "required": [ "category", "senderEmail", "appVersion", "message", "attachments", "bugType", "feature" ], "description": "Transient in-memory UI draft. Arbitrary syntactically valid email is permitted. The synthetic PublicFeedback authoring record remains restricted to example.com. Never persist or transmit this draft." }, "RichPublicHref": { "anyOf": [ { "$ref": "#/$defs/ExternalPublicHref" }, { "type": "string", "minLength": 29, "maxLength": 2048, "format": "uri", "pattern": "^https://linear\\.app/changelog/[^\\s\\x00-\\x1f<>]+$" } ] }, "RichInline": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "kind", "text" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "code" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "kind", "text" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "link" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "href": { "$ref": "#/$defs/RichPublicHref" } }, "required": [ "kind", "text", "href" ] } ] }, "RichText": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4000 }, { "type": "array", "items": { "$ref": "#/$defs/RichInline" }, "minItems": 1, "maxItems": 128 } ], "description": "Literal text or safe text/code/link runs. No HTML, nesting or style attributes. Relationship validation bounds the total to 4,000 Unicode characters and validates every link." } } }, "sources": [ { "id": "public-store", "url": "https://www.raycast.com/store", "evidence": "evidence/capture/pages/store-1440.json", "claim": "Observed public object fields and collection appearance, not network schema." }, { "id": "public-pricing", "url": "https://www.raycast.com/pricing", "evidence": "evidence/capture/pages/pricing-1440.json", "claim": "Dated public price display; fixture values are not current commercial advice." }, { "id": "public-notes", "url": "https://www.raycast.com/core-features/notes", "evidence": "evidence/inventory/secondary/notes-1440.json", "claim": "Public feature page composition." }, { "id": "public-blog", "url": "https://www.raycast.com/blog", "evidence": "evidence/inventory/secondary/blog-1440.json", "claim": "Public article list anatomy." }, { "id": "public-feedback", "url": "https://www.raycast.com/feedback", "evidence": "evidence/inventory/boundary/feedback-1440.json", "claim": "Visible anonymous fields; no submission was made." }, { "id": "public-login", "url": "https://www.raycast.com/users/sign_in", "evidence": "evidence/inventory/boundary/signin-1440.json", "claim": "Public sign-in entry only." }, { "id": "public-sdk", "url": "https://github.com/raycast/extensions", "evidence": "evidence/source-assets/public-source/extensions-repo.json", "claim": "A public native extension SDK/repository exists; it does not establish website backend schemas." }, { "id": "local-runtime", "path": "site/assets/reference.js", "claim": "Actual local event handlers and exports." }, { "id": "local-styles", "path": "site/assets/reference.css", "claim": "Actual local tokens, class APIs, responsive rules, and reduced-motion behavior." } ], "crossRecordRules": [ { "id": "identity", "rule": "IDs and slugs are case-sensitive stable identifiers, never derived at render time from a display title. Each type has unique id; Extension and Article also have unique slug. Reference strings must resolve within the same fixture bundle." }, { "id": "null-is-missing", "rule": "Nullable properties are required keys. Use null when unknown. Empty required text and absent keys are malformed. Never coerce null to the string null or invent zero counts." }, { "id": "plan-money", "rule": "free requires both prices 0; fixed requires both prices positive integer cents and annualMonthlyUsdCents <= monthlyUsdCents; contact requires both null. Amounts are USD per person per month; the annual display is a monthly equivalent. Do not multiply it into a charge." }, { "id": "article-blocks", "rule": "Paragraph, heading, and caption language must be null; code language is text, bash, javascript, typescript, or json. Text remains literal, including markup-like strings." }, { "id": "assets", "rule": "Every file must exist below site/assets with the declared byteLength and SHA-256. Font dimensions are null; other asset dimensions are positive. Decorative assets require empty alt; informative image assets require non-empty alt. A font has empty alt." }, { "id": "feedback", "rule": "Fixture email domain is example.com. Only descriptors for selected files are retained in memory. No bytes, data URLs, real names, credentials, or file-system paths are stored in the fixture. Whitespace-only message is invalid. Fixture schema limits do not claim undocumented production limits." }, { "id": "collection", "rule": "loading, empty, and permission have no items. loading has null receivedAt/expiresAt. Every other fixture has both UTC timestamps and expiresAt >= receivedAt. ready with zero items normalizes to empty. A ready/partial snapshot with expiresAt <= injected now becomes stale without dropping available items. Permission results always clear prior items." }, { "id": "feedback-conditional", "rule": "category=bug-report requires bugType not_working/crashing/freezing (default not_working) and permits optional feature. category=feature-request has bugType=null and permits optional feature. billing-issue, ios, other have both fields null. Hidden draft controls may retain local values for switching back but canonicalize irrelevant fields to null. Local optionality does not claim production server validation." } ], "collectionReducer": { "status": "executable model in data-contract-tests.mjs; current state selector is a local message specimen, not a remote data loader", "clock": "Inject now; fixtureClock is 2026-09-18T23:00:00Z. Never use wall-clock age to silently change the published research date.", "freshForMs": 86400000, "maximumItems": 500, "ordering": "Preserve first accepted ID position; choose its highest revision. An equal-revision identical duplicate is discarded. Equal-revision contradictory records quarantine that ID and report conflict. A newer revision can resolve that conflict. Invalid records are dropped and counted; remaining records produce partial state.", "race": "Only the response whose requestId equals the latest issued request may commit. Older or future unissued response IDs leave state unchanged. Cancel by incrementing latestRequestId; do not show an aborted request as an error.", "failure": "Offline/error preserve a last valid in-memory snapshot unless permission is now denied. Retry is an explicit button and starts one new request; no automatic polling, exponential retry, background sync, or optimistic mutation.", "timeoutMs": 10000, "timeoutStatus": "Reconstructed acceptance rule for future loaders; existing local form completes after 450 ms and has no remote timeout.", "persistence": "No durable cache, service worker, or localStorage. Stale/offline examples are fixture states and survive only in the current document." }, "routing": { "mode": "Static sibling HTML pages with relative links; no SPA, server rewrite, login guard, or dynamic filesystem route.", "pageOwner": "Each HTML document owns one main landmark, one h1, one title and its active navigation state. Every catalog has a unique container ID; first [data-filter] uses q/category, subsequent toolbars use q_/category_. Keep DOM order stable.", "catalog": { "queryKey": "q", "categoryKey": "category", "defaults": { "q": "", "category": "all" }, "read": "URLSearchParams.get reads first occurrence; trim leading/trailing whitespace. Apply known select options only. Unknown categories become all and are removed when initial filtering canonicalizes the URL.", "match": "NFKD; remove U+0300..U+036F; toLocaleLowerCase(en); substring search over data-search. Then AND with exact equality against the entire data-category string (labels may contain spaces). Preserve DOM order.", "write": "On every input/change, replaceState current URL; preserve other toolbars, unrelated query keys and fragment. Remove this toolbar's empty query and all category. set() collapses duplicate recognized parameters. No history entry per keystroke.", "clear": "[data-clear-filter] clears query only, retains selected category, emits input and focuses input. To reset all, explicitly set category to all before dispatching input.", "history": "Ordinary links use native history. Reload reconstructs catalog state from URL. Browser Back is not an undo stack for individual filter keystrokes.", "selection": "Cards/links navigate; there is no collection selection, bulk mutation, saved view, remote sort, pagination, infinite loading, or drag reorder in this local reference.", "directLink": "revealHash decodes the ID and reveals a hidden target without changing filters. Its container count becomes N visible items · includes linked item, including that target, and its empty notice hides. Announces that other filters remain applied. A later filter edit may hide the target again.", "additionalCatalogKeys": { "query": "q_", "category": "category_", "derivation": "The first [data-filter] in document order uses q/category. Every later binding suffixes its data-filter container ID; values are independent." } }, "search": { "source": "data/search-index.json", "schema": { "required": [ "title", "category", "url" ], "optional": [ "description", "keywords" ] }, "fetches": 1, "limit": 40, "order": "authored index order", "match": "Same normalization; substring across title, category, keywords; empty query includes all.", "keyboard": "Ctrl/Cmd+K toggles; opening focuses input; ArrowDown enters results; Up/Down traverse without wrapping; Up on first returns to input; Enter follows only when exactly one result; Escape closes native dialog and returns focus.", "persistence": "Query and results remain in the current document when closed; reload resets search. Global search does not write q/category.", "failure": "Show Search could not load. Use the page navigation or reload this page. Full site navigation remains available.", "security": "Every url is validated as LocalHref before release. Text uses textContent. Dynamic href assignments require the same allow-list validation at ingestion." }, "tabs": "[data-tabs] owns [role=tab] and aria-controls panels. One selected tab, roving tabIndex 0/-1; click or Left/Right/Home/End both focus and activate; arrows wrap. State stays in document; no URL or durable storage.", "segmented": "[data-segmented] buttons use aria-pressed; only selected button has tabindex=0. Click or Left/Right/Home/End selects and dispatches bubbling selectionchange with detail.value = data-value or trimmed label; arrows wrap, Home/End reach endpoints. No multi-select or persistence.", "billing": "Each pricing group has uniquely named native radios carrying data-billing and value=annual|monthly. [data-billing]:checked chooses cadence within the nearest [data-pricing]. [data-price-annual] and data-price-monthly carry dollar strings. Tier selection applies pro=[8,10], plus=[16,20], max=[40,50], scoped to the nearest .price-card. Change amount, cadence note and tier entitlement together. No checkout, charges, taxes or real entitlement change.", "pageInventory": "reference-data/site-build.json" }, "runtimeExports": [ { "name": "toast(message: string): void", "rule": "Create/reuse #toast role=status, textContent only, last call replaces content and restarts 4000 ms dismissal; no queue." }, { "name": "copyText(text: string, trigger?: HTMLElement): Promise", "rule": "On successful user-initiated Clipboard API write, show toast and trigger label Copied for 1800 ms; on failure return false, keep visible source text, offer manual copy. Never copy automatically on load." }, { "name": "openDialog(dialog: HTMLDialogElement, trigger?: HTMLElement): void", "rule": "No-op if absent or already open; remember opener in WeakMap, showModal, focus first input/autofocus/button/link in source order. On close return focus when opener is connected and enabled. Native Escape cancels. Click outside dialog bounding box closes." }, { "name": "safeLocalHref(value: unknown): string | null", "rule": "Runtime same-package page/resource guard; rejects controls/backslashes, encoded slash/backslash/NUL, schemes, leading slash and parent paths, then enforces same origin and package prefix. Navigation ingestion uses the stricter LocalHref schema; assets also use this helper." } ], "localFeedback": { "binding": "form[data-local-form]", "requiredElements": "[type=submit], [data-form-feedback]; optional input[type=email], textarea[required], [data-form-mode]. Each visible field has an explicit label and help/error ID.", "validation": "On submit preventDefault. Ignore while pending. Email uses /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(trimmedEmail); required textarea must contain non-whitespace. Mark first invalid, focus it, retain all entries; input removes its aria-invalid.", "submit": "Valid -> busy disabled button, Checking…; wait 450 ms; success/error/offline selected by data-form-mode; restore button and retain values for all outcomes.", "fileSelection": "Maximum 5 files, each <= 20 * 1024 * 1024 bytes. Validation displays only the count or reason; no file bytes read/uploaded. Current form validation does not submit files.", "successCopy": "Example validated. No data was sent or stored.", "server": "There is no POST URL, authentication flow, queue, email delivery, or account mutation.", "conditional": { "trigger": "Bug Report shows bug type and Feature; Feature Request shows Feature only; Billing Issue, iOS and Other show neither.", "show": "Place conditional controls after version and before Description; do not move focus; disable controls while hidden.", "bugTypes": { "not_working": "Not working as expected", "crashing": "Raycast Crashing", "freezing": "Raycast Freezing" }, "features": [ "AI", "Applications", "Auto Quit", "Calculator", "Calendar/My Schedule", "Clipboard History", "Cloud Sync", "Custom Themes", "Deeplinks", "Dictation", "Extensions", "Flight Tracker", "Focus", "Hyper Key", "Notes", "Quicklinks", "Script Commands", "Search Files", "Settings", "Snippets", "Store", "Window Management", "Other" ], "defaults": "bugType=not_working; feature=null placeholder Select a feature; optional feature under this local contract.", "return": "Preserve chosen values in document memory when switching away/back; all unrelated draft fields remain intact.", "evidence": [ "evidence/inventory/closure/feedback-select-bug-report-confirmed-1440.json", "evidence/inventory/route-tail/feedback-category-feature-request-1440.json" ], "source": "https://www.raycast.com/feedback" }, "noScript": "Authored forms use method=dialog so module-load failure cannot navigate with a GET query containing entered data.", "draftSchema": "FeedbackDraft", "fixtureSchema": "PublicFeedback" }, "persistence": { "url": [ "catalog q", "catalog category", "section fragment" ], "documentMemory": [ "open menu", "dialog query", "tab/segmented choice", "billing preview", "form entries", "file selection descriptors", "toast timeout" ], "durable": [], "cookies": false, "localStorage": false, "sessionStorage": false, "indexedDB": false, "serviceWorker": false, "refresh": "Resets local controls to authored HTML defaults; browser may restore native form state independently. Do not promise draft recovery after reload." }, "analytics": { "enabled": false, "remoteEndpoints": [], "analyticsCalls": [], "auditing": "Browser/network tests assert no third-party requests or non-GET submissions. There is no persisted user action log.", "futureLocalEvents": [ { "name": "catalog_filter_changed", "fields": [ "resultCount", "category" ], "forbidden": [ "q", "search text", "email", "message", "file names" ] }, { "name": "reference_copy_result", "fields": [ "success" ], "forbidden": [ "copied content" ] }, { "name": "local_form_result", "fields": [ "success|error|offline" ], "forbidden": [ "form values" ] } ], "futureRule": "These names are reserved for test-only CustomEvents if needed; current runtime emits only selectionchange, not these events. No timestamp, identifier, IP, fingerprint, endpoint, cookies, or telemetry SDK." }, "capabilities": [ { "role": "anonymous visitor", "action": "read public reference, filter, search, change local specimen state", "allowed": true, "effect": "Read-only browser UI; static same-site GET only." }, { "role": "anonymous visitor", "action": "copy explicit visible text", "allowed": true, "effect": "Browser permission and a user gesture required; failure has manual copy fallback." }, { "role": "anonymous visitor", "action": "validate local feedback", "allowed": true, "effect": "Memory-only validation; no network/storage or message sent." }, { "role": "anonymous visitor", "action": "open official public or sign-in source link", "allowed": true, "effect": "Explicit external navigation leaves the local reference; do not forward query, email, or draft content." }, { "role": "any local role", "action": "install extension, submit real feedback, authenticate, charge, edit tenant/account", "allowed": false, "effect": "Show boundary copy and explicit official link; do not synthesize entitlement from plan selection." } ], "exclusions": [ { "id": "PRIVATE-ACCOUNT", "surface": "Account sessions, credentials, personal settings", "publicAttempt": "evidence/inventory/boundary/settings-boundary-1440.json", "observedUrl": "https://www.raycast.com/users/sign_in?return_to=%2Fsettings%2Fsessions", "recoveryLedger": "reference-data/contract-recovery-ledger.json", "reconstruction": "Local permission notice plus explicit official sign-in link.", "remainingUncertainty": "Authenticated account UI, session invalidation, authorization errors, and account persistence.", "unblock": "Authorized account access and permission to inspect read-only states; no credential request is needed for the public package." }, { "id": "PRIVATE-BILLING", "surface": "Subscription changes, checkout, invoices and payment instruments", "publicAttempt": "evidence/inventory/boundary/upgrade-boundary-1440.json", "observedUrl": "https://www.raycast.com/upgrade", "recoveryLedger": "reference-data/contract-recovery-ledger.json", "reconstruction": "Dated public pricing preview and boundary notice only.", "remainingUncertainty": "Tax, regional pricing, proration, payment failure, billing authorization, refunds.", "unblock": "Authorized test billing account and an approved non-charge sandbox." }, { "id": "PRIVATE-ORGANIZATION", "surface": "Private organization admin, members, roles, invites and audit events", "publicAttempt": "evidence/inventory/state-routes.json", "observedUrl": "https://www.raycast.com/settings/organizations/new?open=true", "recoveryLedger": "reference-data/contract-recovery-ledger.json", "reconstruction": "Public Teams marketing and a sign-in-required fixture.", "remainingUncertainty": "Role names and hierarchy, tenant isolation, invite lifecycle and audit retention.", "unblock": "Authorized multi-role test tenant and approved read-only inspection scope." }, { "id": "NATIVE-RUNTIME", "surface": "Installed desktop/iOS app, extension installation and OAuth", "publicAttempt": "evidence/source-assets/public-source/extensions-docs.json", "observedUrl": "https://developers.raycast.com/", "recoveryLedger": "reference-data/contract-recovery-ledger.json", "reconstruction": "Public screenshots and local command-window specimen; no native API execution.", "remainingUncertainty": "Native OS permission prompts, keychain, installation, OAuth and sync behavior.", "unblock": "Authorized native application/device environment and approved test extensions." }, { "id": "PRIVATE-WEB-API", "surface": "Website server schemas, private component source, experiments and telemetry", "publicAttempt": "evidence/source-assets/public-source/fetches.json", "observedUrl": "https://github.com/raycast/extensions", "recoveryLedger": "reference-data/contract-recovery-ledger.json", "reconstruction": "This local schema, CSS classes and DOM event API.", "remainingUncertainty": "Production endpoints, schema versions, service errors, experiment allocation and analytics contracts.", "unblock": "Authorized first-party backend/component documentation with version identifiers." } ], "budgets": [ { "id": "network", "owner": "reference implementation maintainer", "threshold": "0 third-party automatic requests; 0 POST/PUT/PATCH/DELETE; no authentication cookies", "method": "Playwright request recorder plus fetch/XHR/sendBeacon/WebSocket audit on initial load and every local action", "kind": "acceptance target; consult verification results for measured status" }, { "id": "assets", "owner": "reference implementation maintainer", "threshold": "Shared reference.css <= 100 KiB; reference.js <= 50 KiB; fonts <= 150 KiB combined; first viewport images <= 1500 KiB; each below-fold evidence image <= 1500 KiB; lazy-load offscreen captures", "method": "File byte checks and browser resource records; no autoplay media; font-display swap", "kind": "local budget" }, { "id": "filter", "owner": "reference implementation maintainer", "threshold": "500-item catalog filter completes <= 100 ms at p95 across 20 inputs on recorded host; no input task > 200 ms", "method": "Performance timing in Playwright; record host/browser/data/viewport; do not infer real-user INP from this local timing", "kind": "local budget" }, { "id": "render", "owner": "reference implementation maintainer", "threshold": "Cold local load LCP <= 2500 ms and CLS <= 0.1 at 390x844 and 1440x1000, 3 runs; no post-load layout shift from images without dimensions", "method": "PerformanceObserver probe with cache disabled; retain raw timing and environment", "kind": "local budget; not production SLA" }, { "id": "memory", "owner": "reference implementation maintainer", "threshold": "<=500 extension rows, <=40 global search result links, <=80 article blocks, <=5 attachment descriptors; no video decoding by default", "method": "Contract limits plus DOM node counts; no native heap assertion without a browser-specific measurement", "kind": "local budget" }, { "id": "accessibility", "owner": "accessibility reviewer, independent of author", "threshold": "WCAG 2.2 AA local target: no critical/serious automated issues; text 4.5:1 normal, 3:1 large; controls/focus 3:1; pointer targets >=24x24 CSS px or documented spacing exception; coarse action buttons (including small), icon/copy/search/menu controls >=44x44; fine-pointer button heights retain 36px default, 28px small and 44px large", "method": "Keyboard, reduced motion, forced colors, 320px reflow, 200% text zoom and 400% page zoom checks; manual screen-reader results must name actual tested browser/AT", "kind": "acceptance target, not certification" }, { "id": "compatibility", "owner": "reference implementation maintainer", "threshold": "Native dialog, ES modules, optional chaining, fetch, Unicode normalize, CSS grid, :has and dvh required. Recorded installed Chromium is the measured browser; current Firefox/Safari are follow-up compatibility targets until executed.", "method": "Browser stack wrapper + Playwright actual launch; preserve exact versions and untested targets", "kind": "verified boundary must be read from run evidence" } ], "governance": { "owner": "Pan Out reference implementation maintainer (package author role)", "designReviewOwner": "independent reference fidelity reviewer", "accessibilityOwner": "independent accessibility reviewer", "releaseOwner": "repository owner or their authorized release operator", "version": "semver for this local contract; unrelated to Raycast app or SDK versions", "patch": "Copy correction, evidence link repair, or compatible token correction with no contract changes.", "minor": "New optional record field with documented fallback, new component variant, or added page. Existing fixtures and links continue to work.", "major": "Rename/remove field, change default behavior, route ID, persistence, permission, or data meaning. Include migration and compatibility tests.", "contribution": "Name the public inventory row and evidence; update source map, component/state ledger, contract and fixtures; run data plus UI checks; document intentional mismatch and submit with screenshots at 390/768/1440/1920. Review by a second person/context before release.", "migration": "No end-user database exists. Migrate authoring JSON deterministically in a local branch, preserve IDs or keep old anchors, regenerate static files, compare manifests, then verify all links and deep links. Unsupported major schema versions fail closed at authoring validation.", "rollback": "Republish the last known verified site/ artifact under the same private deployment name, restore its matching contract/fixtures/source manifests and invalidate later scores. No account or database rollback is possible or needed.", "flags": "No remote flag or experiment provider. Local data-form-mode and state select are explicit specimen controls; they cannot enable private actions. Emergency rollback removes a broken link/control or reverts the static artifact.", "freshness": "Recheck public source URLs and pricing/date claims after 30 days or when a source changes; keep capture date visible until recaptured. Never update a date without new evidence.", "exceptions": "Record ID, need, affected files, owner, source, user consequence, review date and removal test in ITERATION-LOG.md. No undocumented geometry or data exceptions.", "handoff": "Four briefs in extension-briefs.json are authored tasks, not passes. Independent execution must produce all six stage records and verification artifacts on a frozen local reference." }, "sourceOfTruth": [ { "concern": "public denominator", "path": "reference-data/independent-component-inventory.json", "owner": "independent inventory researcher", "rule": "Use observed families and source namespaces to choose work; never derive expected scope from rendered examples." }, { "concern": "local component anatomy and page recipes", "path": "reference-data/catalog.mjs", "owner": "reference implementation maintainer", "rule": "Use stable component IDs; update generated ledgers and pages through build-site.mjs." }, { "concern": "tokens, layout, responsive and modes", "path": "site/assets/reference.css", "owner": "reference implementation maintainer", "rule": "Actual computed local rules win over a prose paraphrase; reconcile discrepancies before release." }, { "concern": "bindings, events and local interaction", "path": "site/assets/reference.js", "owner": "reference implementation maintainer", "rule": "Current executable source is local runtime authority; do not call simulated states real network behavior." }, { "concern": "record types and ingestion policy", "path": "reference-data/implementation-contract.json", "owner": "reference implementation maintainer", "rule": "$defs and crossRecordRules jointly define valid authoring records." }, { "concern": "synthetic examples", "path": "site/data/fixtures.json", "owner": "reference implementation maintainer", "rule": "Valid and intentionally invalid data are separate; render only validated selected records." }, { "concern": "data verification", "path": "evidence/verification/data-contract-tests.mjs", "owner": "independent verifier", "rule": "Read results and their input hashes; a source change invalidates prior results." }, { "concern": "public/private recovery boundary", "path": "reference-data/contract-recovery-ledger.json", "owner": "evidence researcher", "rule": "Link exact recovery IDs; status is determined by retained attempts, not this implementation document." }, { "concern": "junior execution", "path": "reference-data/extension-briefs.json", "owner": "independent junior evaluator", "rule": "Authored tasks are not passes; preserve actual implement/verify artifacts." }, { "path": "reference-data/font-subset.json", "rule": "Local Geist Mono Latin/technical subset, preserving source glyph advances and variable weight axis; original binary remains evidence. Never rewrite original fixture asset hashes to the subset.", "concern": "Derived guide font subset", "owner": "asset maintainer" } ], "commands": { "cwd": "repository root", "prerequisites": "Node 22+; Python 3.10+ for static HTTP; no site dependency install or bundler. This run used Node 24.13.1, globally installed Playwright 1.62.1 and Chromium 152.0.7977.42 through the repository wrapper.", "browserStack": ".agents/skills/design-research/scripts/verify-browser-stack.sh", "build": "node designs/raycast/reference-data/build-site.mjs", "contractTest": "node designs/raycast/evidence/verification/data-contract-tests.mjs", "serve": "python3 -m http.server 4178 --bind 127.0.0.1 --directory designs/raycast/site", "browserTest": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/verify-site.cjs http://127.0.0.1:4178/", "scope": "The builder owns build-site.mjs and verify-site.cjs; their presence and results must be verified before release. Documentation is not execution evidence.", "recoverSourceCSS": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/recover-css-matches.cjs", "compareSourceReplay": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/compare-source-replay.cjs", "normalizeGeometry": "node --max-old-space-size=8192 designs/raycast/evidence/verification/normalize-geometry.mjs", "systemTest": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/check-system.cjs http://127.0.0.1:4178/", "evaluateSourceComparison": "node designs/raycast/evidence/verification/evaluate-source-comparisons.mjs", "verifyDerivedParts": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/verify-derived-replay.cjs", "verifyDerivedModifiers": ".agents/skills/design-research/scripts/run-playwright.sh designs/raycast/evidence/verification/verify-source-derived-variants.cjs", "freezeDerivedInput": "node designs/raycast/evidence/verification/freeze-derived-input.mjs", "geometryAudit": "node --max-old-space-size=8192 designs/raycast/evidence/verification/verify-geometry-contracts.mjs" }, "statePresentation": { "CollectionEnvelope.ready": "data-state-demo select value success", "no-match-after-filter": "data-state-demo select value filtered; this is separate from an empty source", "otherEnvelopeStates": "loading,empty,partial,stale,error,offline,permission map by name", "boundary": "The stock data-state-demo changes copy only; it is not the collection adapter exercised by the independent junior task." }, "familyComposition": { "version": "1.1.0", "fixtureAuthority": "Synthetic authoring data; published source identity/media cases are separately labelled", "browserModel": "site/assets/family-ui-model.mjs", "browserModelDerivation": "Exact prefix of family-model.mjs before validateRelations; browser entry omits Node-only relation and collection-ingestion exports.", "baseCSS": "site/assets/family-base.css", "baseCSSDerivation": "Exact shared font/token/reset prefix of reference.css before .navbar-wrap; imports fallback-fonts.css.", "verificationReports": [ "evidence/verification/family-remediation/data-results.json", "evidence/verification/family-remediation/browser-results.json", "evidence/verification/family-remediation/anatomy-results.json" ], "authority": "Local reconstruction from independently inventoried public anatomy; no authoritative production API claims", "contract": "reference-data/remediation/family-contracts.json", "fixtures": "site/data/family-fixtures.json", "model": "site/assets/family-model.mjs", "renderer": "reference-data/remediation/family-render.mjs", "objects": [ { "id": "O-extension", "schema": "Extension", "detailSchema": "ExtensionDetail", "familyId": "F-extension-detail" }, { "id": "O-publisher", "schema": "Publisher", "detailSchema": null, "familyId": "F-author-profile" }, { "id": "O-plan", "schema": "Plan", "detailSchema": null, "familyId": "F-pricing" }, { "id": "O-model", "schema": "AIModel", "detailSchema": null, "familyId": "F-ai-models" }, { "id": "O-task-demo", "schema": "ScriptedTask", "detailSchema": "ToolGroup", "familyId": "F-ai" }, { "id": "O-release", "schema": "Release", "detailSchema": null, "familyId": "F-changelog-list" }, { "id": "O-article", "schema": "Article", "detailSchema": null, "familyId": "F-resource-article" }, { "id": "O-story", "schema": "Story", "detailSchema": null, "familyId": "F-customer-story" }, { "id": "O-template", "schema": "ExtensionTemplate", "detailSchema": null, "familyId": "F-template-detail" }, { "id": "O-asset", "schema": "Asset", "detailSchema": null, "familyId": "F-press" }, { "id": "O-feedback", "schema": "PublicFeedback", "detailSchema": "FeedbackDraft", "familyId": "F-feedback" }, { "id": "O-account-entry", "schema": "AccountEntryAttempt", "detailSchema": null, "familyId": "F-signin" }, { "id": "O-job", "schema": "JobOpening", "detailSchema": null, "familyId": "F-careers" }, { "id": "O-keyboard", "schema": "KeyboardProduct", "detailSchema": null, "familyId": "F-keyboard" } ], "relationships": [ { "id": "publisher-extension-join", "types": [ "Publisher", "ExtensionDetail" ], "rule": "Every publisher extensionIds entry resolves to one Extension.id. ExtensionDetail.publisherId resolves to Publisher.id; unknown IDs quarantine that detail instead of rendering an unrelated card." }, { "id": "command-history-ownership", "types": [ "ExtensionDetail", "ExtensionVersion" ], "rule": "Command IDs are unique within a detail. Every version.extensionId equals detail.extensionId; versions sort descending by valid publishedAt, then stable id." }, { "id": "public-rich-content", "types": [ "ExtensionVersion", "ExtensionTemplate" ], "rule": "A paragraph or list item is literal text or at most 128 text/code/link runs, totaling at most 4,000 Unicode characters. Escape every text and attribute value. Only validated HTTPS public destinations are links; HTML, nested runs, styles, event handlers and unsafe destinations reject the record. Original fixture prose is distinct from in-memory source-text conditioning used by fidelity tests." }, { "id": "task-tool-state", "types": [ "ScriptedTask", "ToolGroup", "ToolCall" ], "rule": "IDs are unique within their containing task/group. A complete tool call has nonempty outputSummary. Queued/running/blocked tools never render a completed result label." }, { "id": "plan-model-join", "types": [ "AIModel", "Plan" ], "rule": "Each AIModel.planIds value resolves to Plan.id. A null capability score means Not stated; it never becomes zero or five stars." }, { "id": "source-asset-join", "types": [ "Publisher", "Story", "ExtensionTemplate", "KeyboardProduct" ], "rule": "Non-null asset IDs resolve to Asset.id. Missing media preserves its aspect-ratio frame, descriptive text and explicit unavailable state." }, { "id": "account-secret-boundary", "types": [ "AccountEntryAttempt" ], "rule": "The fixture contains only passwordPresent, never a password or confirmation token. Provider mode requires a provider; other modes require null. A ready-for-handoff state is not authenticated." }, { "id": "feedback-ui-boundary", "types": [ "PublicFeedback", "FeedbackDraft" ], "rule": "Both use message <=4000 Unicode code points, appVersion <=40, <=5 files each <=20971520 bytes, and category-dependent bugType/feature. PublicFeedback restricts synthetic email to example.com and fixture attachment types/names. The in-memory FeedbackDraft accepts any syntactically valid email and arbitrary native file types, including empty MIME, with bounded metadata. FeedbackDraft never receives a synthetic id or success timestamp and is never persisted or transmitted." }, { "id": "template-command-safety", "types": [ "ExtensionTemplate" ], "rule": "installCommand is displayed/copied as inert text only. Never pass it to a shell. organizationRequired remains an explicit handoff boundary." } ] } }