@jarenjs/view 0.34.0

package/schemas/jaren-vnode-safe.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-vnode-safe/0.1",
+  "title": "Jaren safe vnode document",
+  "description": "The SAFE vnode profile: the vnode grammar with the structural constraints a schema can express for an UNTRUSTED document. Tag and property names must be bare identifiers (closing tag- and attribute-name injection), property names may not begin with `on` (no inline handlers) and may not be a scripting sink, and a set of document-embedding tags is forbidden. This is a defense-in-depth pre-filter, NOT the authoritative safety boundary: the runtime safe render policy (`createSafePolicy`, applied by `{ safe: true }`) restricts tags to a full allow-list, sanitizes URL attributes and inline styles, and strips event/widget bindings — things a static schema cannot do. Validate with this AND render in safe mode. See safe.js and VIEW-FORMAT.md.",
+  "$ref": "#/$defs/vnode",
+  "$defs": {
+    "vnode": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "$ref": "#/$defs/element" },
+        { "$ref": "#/$defs/list" }
+      ],
+      "description": "No widget branch: a widget mounts imperative JavaScript, which an untrusted document must not do, so `jaren-widget` is not a safe-profile node."
+    },
+    "safeName": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9-]*$",
+      "description": "A bare identifier: a letter followed by letters, digits or hyphens. No spaces, angle brackets, equals signs, slashes, colons or quotes — the characters every structural-injection payload needs."
+    },
+    "element": {
+      "type": "array",
+      "minItems": 1,
+      "prefixItems": [
+        {
+          "allOf": [
+            { "$ref": "#/$defs/safeName" },
+            {
+              "not": {
+                "enum": [
+                  "script", "style", "iframe", "object", "embed", "base",
+                  "link", "meta", "noscript", "template", "frame", "frameset",
+                  "html", "head", "body", "title", "foreignObject", "portal",
+                  "jaren-widget"
+                ]
+              },
+              "description": "Document-structure, script/style carriers and document-embedding elements are forbidden. The runtime policy enforces the positive allow-list; this rejects the highest-risk tags structurally."
+            }
+          ]
+        }
+      ],
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/props" },
+          { "$ref": "#/$defs/vnode" }
+        ]
+      }
+    },
+    "list": {
+      "type": "array",
+      "prefixItems": [
+        {
+          "allOf": [
+            { "not": { "type": "string" } },
+            { "$ref": "#/$defs/vnode" }
+          ]
+        }
+      ],
+      "items": { "$ref": "#/$defs/vnode" }
+    },
+    "props": {
+      "type": "object",
+      "propertyNames": {
+        "allOf": [
+          { "$ref": "#/$defs/safeName" },
+          {
+            "not": { "pattern": "^[Oo][Nn]" },
+            "description": "No property name may begin with `on`: inline event-handler attributes are forbidden, and so is the `on` binding object (an untrusted view must not bind host actions)."
+          },
+          {
+            "not": { "pattern": "^[Ii][Ss]$" },
+            "description": "The `is` attribute is forbidden: it upgrades an element to a registered customized built-in when the markup is parsed, running host-registered code."
+          },
+          {
+            "not": {
+              "pattern": "^([Ii][Nn][Nn][Ee][Rr]|[Oo][Uu][Tt][Ee][Rr])[Hh][Tt][Mm][Ll]$|^[Ss][Rr][Cc][Dd][Oo][Cc]$|[Dd][Aa][Nn][Gg][Ee][Rr][Oo][Uu][Ss][Ll][Yy]"
+            },
+            "description": "The HTML-parsing sinks (innerHTML, outerHTML, srcdoc, dangerouslySetInnerHTML) are forbidden by name, in any casing."
+          }
+        ]
+      },
+      "properties": {
+        "key": { "type": ["string", "number"] },
+        "style": { "type": ["string", "object"] }
+      },
+      "additionalProperties": {
+        "type": ["string", "number", "boolean", "null"]
+      },
+      "description": "A safe props object: identifier names only, no on* bindings, no HTML sinks. URL and style VALUES still need the runtime policy — a schema cannot read a `javascript:` scheme out of an href."
+    }
+  }
+}

package/schemas/jaren-vnode.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-vnode/0.1",
+  "title": "Jaren vnode document",
+  "description": "The Jaren view vocabulary: a user interface as a JSON value. Text is a string or number; an element is an array [tag, props?, ...children]; an array whose first item is not a string is a list spliced into its parent; null and booleans render nothing. See docs/VIEW-FORMAT.md for the normative contract.",
+  "$ref": "#/$defs/vnode",
+  "$defs": {
+    "vnode": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "$ref": "#/$defs/element" },
+        { "$ref": "#/$defs/widget" },
+        { "$ref": "#/$defs/list" }
+      ]
+    },
+    "element": {
+      "type": "array",
+      "minItems": 1,
+      "prefixItems": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "not": { "const": "jaren-widget" },
+          "description": "The tag name. The reserved widget tag is excluded: a jaren-widget node must satisfy the strict widget shape and can never validate through this generic branch."
+        }
+      ],
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/props" },
+          { "$ref": "#/$defs/vnode" }
+        ]
+      },
+      "description": "An element vnode: [tag, props?, ...children]. When the second item is an object it is the props; every further item is a child."
+    },
+    "list": {
+      "type": "array",
+      "prefixItems": [
+        {
+          "allOf": [
+            { "not": { "type": "string" } },
+            { "$ref": "#/$defs/vnode" }
+          ],
+          "description": "The documented distinction, enforced: an array whose first item IS a string is an element (or a widget), never a list. The first item is still a vnode like every other."
+        }
+      ],
+      "items": { "$ref": "#/$defs/vnode" },
+      "description": "A child list, spliced into the parent's children in place. Distinguished from an element by its first item not being a string."
+    },
+    "widget": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "prefixItems": [
+        {
+          "const": "jaren-widget",
+          "description": "The reserved widget tag."
+        },
+        { "$ref": "#/$defs/widgetProps" }
+      ],
+      "description": "A widget vnode: [\"jaren-widget\", props] mounts a registered JavaScript widget into a host element the renderer owns. A widget node has NO vnode children — the widget owns the host's subtree. The reserved tag is excluded from the generic element branch, so a malformed widget node fails validation instead of passing as a plain element. See docs/VIEW-FORMAT.md section 7."
+    },
+    "widgetProps": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The registered widget name."
+        },
+        "props": {
+          "description": "The widget's JSON props, any JSON value; compared by reference across renders."
+        },
+        "tag": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The host element's tag; default div (producers inside an svg subtree pick an SVG container like g)."
+        },
+        "key": {
+          "type": ["string", "number"],
+          "description": "Reconciliation identity among siblings; never rendered."
+        },
+        "on": {
+          "type": "object",
+          "additionalProperties": {
+            "description": "An opaque event binding, delivered as-is to the renderer's onEvent hook. In @jarenjs/app: an action name, or { action, with?, event?, preventDefault?, stopPropagation? } - event is an array of requested $event field names; the two boolean controls (default false) run synchronously in the native event callback, before the action is queued (APP-FORMAT section 3.1)."
+          },
+          "description": "Event bindings on the HOST element, by DOM event type."
+        },
+        "style": {
+          "type": ["string", "object"],
+          "description": "A CSS declaration string, or an object of declarations (camelCase keys become kebab-case)."
+        }
+      },
+      "additionalProperties": {
+        "type": ["string", "number", "boolean", "null"],
+        "description": "Any other prop applies to the HOST element exactly as on any element vnode."
+      },
+      "description": "The props object of a widget vnode: name/props/tag configure the widget; everything else is a host-element prop."
+    },
+    "props": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": ["string", "number"],
+          "description": "Reconciliation identity among siblings; never rendered."
+        },
+        "on": {
+          "type": "object",
+          "additionalProperties": {
+            "description": "An opaque event binding, delivered as-is to the renderer's onEvent hook. In @jarenjs/app: an action name, or { action, with?, event?, preventDefault?, stopPropagation? } - event is an array of requested $event field names; the two boolean controls (default false) run synchronously in the native event callback, before the action is queued (APP-FORMAT section 3.1)."
+          },
+          "description": "Event bindings by DOM event type."
+        },
+        "style": {
+          "type": ["string", "object"],
+          "description": "A CSS declaration string, or an object of declarations (camelCase keys become kebab-case)."
+        }
+      },
+      "additionalProperties": {
+        "type": ["string", "number", "boolean", "null"],
+        "description": "Any other prop writes through to the DOM: as a property when the node has one, as an attribute otherwise. true renders a bare attribute; false and null remove it."
+      },
+      "description": "The props object of an element."
+    }
+  }
+}