@entropicwarrior/sdoc 0.1.18 → 0.2.0

package/docs/reference/sdoc-authoring.sdoc

@@ -4,7 +4,7 @@
     {
         type: skill
 
-        sdoc-version: 0.1
+        sdoc-version: 0.2
     }
 
     # About @about
@@ -178,7 +178,7 @@ Content of Section B.
 
             **Important:** \`{[.]}\` with the closing brace on the same line creates an empty list — the brace closes the block immediately. Always put the closing \`}\` on a separate line after the items.
 
-            Implicit lists only work for bullet lists (\`-\`) where every item is a single line. For numbered lists, always use the explicit \`{[#]\` block form.
+            Implicit lists work for both bullet (\`-\`) and numbered (\`1.\`, \`2.\`, etc.) items. Each item must be a single line. For multi-line item titles or item body content, use the explicit \`{[.]}\` or \`{[#]\` block form.
 
             **Task lists** — checkbox syntax inside explicit list blocks:
 
@@ -244,6 +244,27 @@ Content of Section B.
             ```
 
             \`borderless\` removes borders and row striping. \`headerless\` treats all rows as data (no header). Flags combine in any order.
+
+            Width and alignment flags control table sizing and position:
+
+            ```
+            {[table 60% center]
+                Endpoint | Status
+                /v2/weather | Active
+            }
+
+            {[table auto]
+                Key | Value
+                Version | 2.0
+            }
+
+            {[table 400px right borderless]
+                v2.0 | Current
+                v1.0 | Deprecated
+            }
+            ```
+
+            Width: \`auto\` (shrink to content), \`NN%\` (percentage), or \`NNpx\` (pixels). Default is 100%. Alignment: \`left\` (default), \`center\`, or \`right\`. All flags compose freely in any order.
         }
 
         # Inline Formatting @inline-formatting
@@ -279,7 +300,7 @@ Content of Section B.
             ![A](a.png =48%) ![B](b.png =48%)
             ```
 
-            Autolinks: \`\<https://example.com\>\`
+            Autolinks: \`\<https://example.com\>\` — angle brackets are optional; bare URLs starting with \`http://\`, \`https://\`, or \`mailto:\` are also auto-linked.
 
             Math: Use \`\$...\$\` for inline math and \`\$\$...\$\$\` for display math. Use \`\\\`\\\`\\\`math\` code fences for multi-line equations. A plain \`\$\` followed by a digit (e.g. \`\$100\`) does not trigger math mode.
         }
@@ -380,7 +401,7 @@ Content of Section B.
             @meta {
                 type: doc
 
-                sdoc-version: 0.1
+                sdoc-version: 0.2
 
                 company: Irreversible Inc.
 
@@ -420,7 +441,7 @@ Content of Section B.
 
             \`tags: tag1, tag2\` — comma-separated tags.
 
-            \`sdoc-version: 0.1\` — SDOC format version. A parser warning is
+            \`sdoc-version: 0.2\` — SDOC format version. A parser warning is
             emitted when this key is missing from \`@meta\`.
         }
 
@@ -441,7 +462,7 @@ Content of Section B.
         {
             Backslash escapes special characters: \`\\\\\` \`\\{\` \`\\}\` \`\\@\`
             \`\\[\` \`\\]\` \`\\(\` \`\\)\` \`\\*\` \`\\~\` \`\\#\` \`\\!\` \`\\\<\`
-            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\`
+            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\` \`\\?\`
 
             A line starting with \`\\#\` renders as a literal \`#\` (not a heading). Use \`\\\$\` to prevent a dollar sign from starting math mode.
         }
@@ -454,6 +475,89 @@ Content of Section B.
                 - **Commas:** commas between list items or scopes are allowed but ignored — use them if you find them readable.
             }
         }
+
+        # Scope Types @scope-types
+        {
+            A \`:type\` annotation on a heading gives the scope semantic meaning. Place it after the optional \`@id\`:
+
+            ```
+            # User Authentication @auth :requirement
+            {
+                The system shall authenticate users via OAuth 2.0.
+            }
+
+            # OAuth Flow :specification @oauth-flow
+            {
+                Implements @auth using the authorization code flow.
+            }
+
+            # Deprecation Notice :warning
+            {
+                This API will be removed in v3.0.
+            }
+            ```
+
+            {[.]
+                - Syntax: \`# Title @id :type\` or \`# Title :type @id\` or \`# Title :type\` — both orderings work
+                - The colon requires whitespace before it: \`# Note: Important\` is NOT a type — the colon is part of the title
+                - Any string is valid. Well-known types: \`schema\`, \`example\`, \`requirement\`, \`specification\`, \`definition\`, \`note\`, \`warning\`, \`test\`, \`task\`, \`api\`, \`config\`, \`deprecated\`, \`comment\`
+                - Works with K&R style: \`# Title :warning {\`
+            }
+
+            The special type \`:comment\` makes a scope that is in the AST but not rendered — useful for editorial notes and AI agent instructions:
+
+            ```
+            # TODO :comment
+            {
+                Rewrite this section after the API stabilises.
+            }
+            ```
+        }
+
+        # Data Blocks @data-blocks
+        {
+            Add \`:data\` to a JSON code fence to have the parser parse the content into structured data on the AST node:
+
+            `````
+            ```json :data
+            {
+                "name": "SDOC",
+                "version": "0.2",
+                "features": ["scopes", "lists", "tables"]
+            }
+            ```
+            `````
+
+            {[.]
+                - Syntax: \` \`\`\`json :data \` — the \`:data\` flag follows the language tag
+                - Invalid JSON produces a parse error
+                - JSON-only in v0.2
+                - Without \`:data\`, JSON code blocks remain raw text (existing behaviour)
+            }
+        }
+
+        # Comments @comments
+        {
+            **Line comments** — \`//\` at the start of a line (after optional indentation) skips the line entirely. Not in the AST, not rendered:
+
+            ```
+            # Config @config
+            {
+                // TODO: add validation
+                The config file uses JSON format.
+
+                // hidden from output
+                See @setup for details.
+            }
+            ```
+
+            {[.]
+                - Mid-line \`//\` has no effect — URLs like \`https://example.com\` are safe
+                - Inside code blocks: \`//\` has no special meaning
+            }
+
+            **Comment scopes** — use the \`:comment\` scope type for structured non-rendered content (see @scope-types above).
+        }
     }
 
     # Common Mistakes @common-mistakes

package/lexica/specification.sdoc

@@ -1,19 +1,20 @@
-# SDOC Specification v0.1 @sdoc-spec
+# SDOC Specification v0.2 @sdoc-spec
 {
     # Meta @meta
     {
         type: doc
 
-        sdoc-version: 0.1
+        sdoc-version: 0.2
     }
 
     # About @about
     {
-        The formal SDOC v0.1 specification. Defines syntax for scopes,
-        lists, tables, code blocks, inline formatting, references, and
-        the meta scope. Includes the formal EBNF grammar. Read for
-        edge cases and parser behaviour questions. For a friendlier
-        user-facing reference, see \`docs/reference/syntax.sdoc\`.
+        The formal SDOC v0.2 specification. Defines syntax for scopes,
+        lists, tables, code blocks, inline formatting, references,
+        the meta scope, scope types, data blocks, and comments.
+        Includes the formal EBNF grammar. Read for edge cases and
+        parser behaviour questions. For a friendlier user-facing
+        reference, see \`docs/reference/syntax.sdoc\`.
     }
 
     # Overview @overview
@@ -51,12 +52,17 @@
         {
             ```
             # Title text @id
+            # Title text @id :type
+            # Title text :type @id
+            # Title text :type
             ```
 
             {[.]
                 - The line must start with `#` (after optional indentation)
                 - Multiple `#` characters are allowed but do not affect depth. Depth comes only from scope nesting
-                - The optional `@id` must appear at the end of the line, separated by whitespace
+                - The optional `@id` must appear at the end of the line (or before `:type`), separated by whitespace
+                - The optional `:type` assigns a scope type (see @scope-types). Both `@id :type` and `:type @id` orderings are valid
+                - `:type` requires whitespace before the colon, so `# Note: Important` is NOT a scope type — the colon is part of the title
                 - If no `@id` is present, the scope has no ID
                 - If you need a literal `@` in the title, escape it (`\@`)
             }
@@ -122,7 +128,7 @@ Content of Section B.
                     - The opener must be the last token on the line (trailing whitespace is allowed)
                     - Applies to `{`, `{[.]`, `{[#]`, `{[table]`, and `{[table <flags>]`
                     - Also works on list-item shorthand lines (e.g., `- Item {`)
-                    - Table options (e.g., `{[table borderless]`) work in K&R style: `# Data {[table borderless]`
+                    - Table options (e.g., `{[table borderless]`, `{[table 60% center]`) work in K&R style: `# Data {[table borderless]`
                     - Escaped braces (`\{`) are not treated as openers
                     - The closing `}` must still appear on its own line
                     - Inline blocks (`{ content }`) are not affected; a line ending with `}` is not treated as K&R
@@ -344,9 +350,33 @@ Content of Section B.
                 {[.]
                     - `borderless` removes all table borders and row striping
                     - `headerless` treats the first row as data (no header row)
-                    - Flags can be combined in any order
+                    - `auto` sets width to shrink-to-content
+                    - A percentage value (e.g. `60%`, `33.3%`) sets an explicit percentage width
+                    - A pixel value (e.g. `400px`) sets an explicit pixel width
+                    - `center` centers the table (auto margins)
+                    - `right` right-aligns the table (margin-left: auto)
+                    - `left` left-aligns the table (default, no extra styles)
+                    - Default width is 100%; default alignment is left
+                    - All flags can be combined in any order
                     - Works with both Allman and K&R brace styles
                 }
+
+                ```
+{[table 60% center]
+    Endpoint | Status
+    /v2/weather | Active
+}
+
+{[table auto right borderless]
+    Key | Value
+    Version | 2.0
+}
+
+{[table 400px]
+    Name | Age
+    Alice | 30
+}
+                ```
             }
         }
 
@@ -387,6 +417,8 @@ Content of Section B.
             ```
 
             Only `http`, `https`, and `mailto` schemes are recognised.
+
+            Bare URLs starting with `http://`, `https://`, or `mailto:` are also auto-linked without angle brackets.
         }
 
         # Images @images
@@ -466,7 +498,7 @@ Content of Section B.
 
         # Escaping @escaping
         {
-            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` and `` \` ``.
+            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` `\?` and `` \` ``.
 
             Escapes are processed before reference detection.
 
@@ -516,6 +548,115 @@ Content of Section B.
                 }
             }
         }
+
+        # Scope Types @scope-types
+        {
+            A scope type annotation provides semantic meaning to a scope. The type is specified with `:typename` on the heading line, after optional `@id`:
+
+            ```
+            # User Authentication @auth :requirement
+            {
+                The system shall authenticate users via OAuth 2.0.
+            }
+
+            # OAuth Flow :specification @oauth-flow
+            {
+                Implements @auth using the authorization code flow.
+            }
+
+            # Important :warning
+            {
+                This API is deprecated and will be removed in v3.0.
+            }
+            ```
+
+            {[.]
+                - Syntax: `# Title @id :type` or `# Title :type @id` or `# Title :type` — both orderings of `@id` and `:type` are supported
+                - The colon in `:type` requires whitespace before it, so `# Note: Important` is NOT a scope type — the colon is part of the title text
+                - Any string is valid as a type name
+                - Well-known types: `schema`, `example`, `requirement`, `specification`, `definition`, `note`, `warning`, `test`, `task`, `api`, `config`, `deprecated`, `comment`
+                - The type is stored on the AST node and available to renderers and tooling
+                - Scope types enable AI agents to filter and navigate by semantic meaning (e.g., "show all requirements", "find tests for this spec")
+                - Works with K&R brace style: `# Title :warning {`
+            }
+
+            # Comment Scopes @comment-scopes
+            {
+                The `:comment` scope type creates a scope that is present in the AST but not rendered in the document output. This is useful for editorial annotations, AI agent instructions, and internal notes:
+
+                ```
+                # TODO :comment
+                {
+                    Rewrite this section after the API stabilises.
+                    @alice please review the error handling.
+                }
+
+                # Agent Instructions :comment
+                {
+                    When summarising this document, focus on the
+                    requirements and skip the implementation details.
+                }
+                ```
+
+                {[.]
+                    - Comment scopes use the standard scope type system — no special syntax beyond `:comment`
+                    - The scope is parsed into the AST (agents and tooling can extract it)
+                    - The scope is not rendered in HTML, PDF, or other visual outputs
+                    - Comment scopes can contain any valid SDOC content (paragraphs, lists, code blocks, nested scopes)
+                    - Useful for structured annotations that are too complex for line comments
+                }
+            }
+        }
+
+        # Data Blocks @data-blocks
+        {
+            A code fence with the `:data` flag causes the parser to parse the content as structured data and attach it to the AST node:
+
+            `````
+            ```json :data
+            {
+                "name": "SDOC",
+                "version": "0.2",
+                "features": ["scopes", "lists", "tables"]
+            }
+            ```
+            `````
+
+            {[.]
+                - Syntax: ` ```json :data ` — the `:data` flag follows the language tag on the opening fence line
+                - The parser parses the JSON content and stores the result on the AST node
+                - Invalid JSON produces a parse error
+                - JSON is the only supported data format in v0.2
+                - Without the `:data` flag, JSON code blocks are treated as raw text (existing behaviour)
+                - Data blocks render visually the same as regular code blocks, but the parsed data is available to tooling and agents
+            }
+        }
+
+        # Line Comments @line-comments
+        {
+            A line starting with `//` (after optional indentation) is a line comment. The line is skipped entirely — it does not appear in the AST and is not rendered:
+
+            ```
+            # Configuration @config
+            {
+                // TODO: add validation rules
+                The config file uses JSON format.
+
+                // This paragraph is hidden from output
+                // but visible in the source file.
+
+                See @setup for installation steps.
+            }
+            ```
+
+            {[.]
+                - The `//` must be at the start of the line (after optional whitespace)
+                - Comment lines are discarded during parsing — they are not present in the AST
+                - Inside code blocks: `//` has no special meaning (code block content is raw)
+                - Mid-line `//` has no special meaning — URLs like `https://example.com` are safe
+                - Use line comments for quick annotations; use comment scopes (@comment-scopes) for structured non-rendered content
+            }
+        }
     }
 
     # Styles, Header, and Footer @styling
@@ -585,7 +726,7 @@ Content of Section B.
                     date: 2026-02-09
                     version: 1.0
                     status: Draft
-                    sdoc-version: 0.1
+                    sdoc-version: 0.2
                 }
                 ```
 
@@ -593,7 +734,7 @@ Content of Section B.
                     - Key matching is case-insensitive
                     - The pattern requires at least one space after the colon (`key: value`, not `key:value`)
                     - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`
-                    - `sdoc-version` identifies the SDOC format version the document targets (current: `0.1`). A parser warning is emitted when this key is missing.
+                    - `sdoc-version` identifies the SDOC format version the document targets (current: `0.2`). A parser warning is emitted when this key is missing.
                     - All other keys are stored as custom properties (e.g., `author`, `date`, `version`, `status`, `tags`)
                     - Sub-scope syntax takes precedence: if both `# Style { path }` and `style: path` exist, the sub-scope value wins
                     - Key:value and sub-scope syntax can be mixed freely in the same meta scope
@@ -713,6 +854,7 @@ Content of Section A.
             - `>` blockquote line
             - `---` / `***` / `___` horizontal rule
             - `` ``` `` code fence
+            - `//` line comment (discarded, not in AST)
         }
 
         Blank lines are allowed anywhere and are ignored.
@@ -731,25 +873,34 @@ Content of Section A.
         scope         = heading ws? block
                       | heading ws? braceless_body
                       | heading_with_opener block_body "}" ;
-        heading       = "#" { "#" } ws title (ws id)? ;
-        heading_with_opener = "#" { "#" } ws title (ws id)? ws block_opener ;
+        heading       = "#" { "#" } ws title
+                          ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ;
+        heading_with_opener = "#" { "#" } ws title
+                          ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ws block_opener ;
         id            = "@" ident ;
+        scope_type    = ":" ident ;   (* id and scope_type may appear in either order *)
         block_opener  = "{" | "{[.]" | "{[#]" | table_open ;
         block         = "{" ws? block_body "}" ;
-        braceless_body = { paragraph | code_block | blockquote | implicit_list
-                         | horizontal_rule | headingless_scope | table_scope
-                         | blank } ;
-
-        block_body    = { blank | paragraph | scope | headingless_scope
-                        | list_scope | table_scope
+        braceless_body = { paragraph | code_block | data_block | blockquote
+                         | implicit_list | horizontal_rule | headingless_scope
+                         | list_scope | table_scope | bare_directive
+                         | line_comment | blank } ;
+
+        bare_directive = "@" ("meta" | "about") (ws block | braceless_body) ;
+        block_body    = { blank | line_comment | paragraph | scope
+                        | headingless_scope | list_scope | table_scope
                         | implicit_list | blockquote | horizontal_rule
-                        | code_block | comma_sep } ;
+                        | code_block | data_block | bare_directive | comma_sep } ;
         headingless_scope = "{" ws? block_body "}" ;
         list_scope    = list_open ws? list_body "}" ;
         list_open     = "{[.]" | "{[#]" ;
         table_scope   = table_open ws? table_body "}" ;
         table_open    = "{[table" { ws table_flag } "]" ;
-        table_flag    = "borderless" | "headerless" ;
+        table_flag    = "borderless" | "headerless"
+                      | "auto" | percentage | pixels
+                      | "left" | "center" | "right" ;
+        percentage    = digit { digit } [ "." digit { digit } ] "%" ;
+        pixels        = digit { digit } "px" ;
         table_body    = table_row { table_row } ;
         table_row     = cell { "|" cell } ;
         list_body     = { blank | comma_sep | scope | list_item_shorthand
@@ -767,15 +918,19 @@ Content of Section A.
         paragraph     = text_line { ws? text_line } ;
         text_line     = line_not_starting_with_command ;
 
-        blockquote    = quote_line { quote_line | blank } ;
+        blockquote    = quote_line { quote_line } ;
         quote_line    = ">" text_line ;
 
         horizontal_rule = "---" | "***" | "___" ;
 
         code_block    = fence_open raw_text fence_close ;
+        data_block    = data_fence_open raw_text fence_close ;
         fence_open    = "```" [lang] [ws "src:" path] [ws "lines:" range] newline ;
+        data_fence_open = "```" lang ws ":data" newline ;
         fence_close   = "```" newline ;
 
+        line_comment  = "//" { any_char } newline ;  (* discarded, not in AST *)
+
         comma_sep     = "," ;
         blank         = newline ;
 
@@ -783,7 +938,10 @@ Content of Section A.
         ```
 
         {[.]
-            - `title` is the remainder of the heading line, excluding the optional trailing `@id`
+            - `title` is the remainder of the heading line, excluding the optional trailing `@id` and `:type`
+            - `scope_type` and `id` may appear in either order after the title
+            - `line_comment` lines are discarded during parsing and do not appear in the AST
+            - `data_block` content is parsed as JSON; invalid JSON produces a parse error
             - If a line starts with a command token, it is not a paragraph line
             - The grammar is line-oriented; practical parsers should operate on lines
         }
@@ -792,10 +950,10 @@ Content of Section A.
     # Open Questions @open-questions
     {
         {[.]
-            - Comment syntax (if any)
             - Duplicate ID resolution (error vs warning vs nearest-scope)
-            - Additional list types (checkboxes, alpha, roman)
+            - Additional list types (alpha, roman)
             - Additional inline formatting (underline)
+            - Additional data block formats beyond JSON (YAML, TOML)
         }
     }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/notion-renderer.js

@@ -246,6 +246,7 @@ function renderNotionBlocks(nodes) {
   // Unwrap document scope wrapper (single root scope)
   if (nodes.length === 1 && nodes[0].type === "scope" && nodes[0].children) {
     const doc = nodes[0];
+    if (doc.scopeType === "comment") return [];
     if (doc.hasHeading && doc.title) {
       // Document title scope: render as top-level toggle heading
       const childBlocks = renderChildren(doc.children, 2, 1);
@@ -290,6 +291,8 @@ function renderNode(node, depth, nestLevel) {
 }
 
 function renderScope(scope, depth, nestLevel) {
+  if (scope.scopeType === "comment") return [];
+
   const level = Math.min(3, Math.max(1, depth));
 
   if (scope.hasHeading === false) {

package/src/sdoc.js

@@ -1,4 +1,9 @@
-const SDOC_FORMAT_VERSION = "0.1";
+const SDOC_FORMAT_VERSION = "0.2";
+
+const KNOWN_SCOPE_TYPES = [
+  "schema", "example", "requirement", "specification", "definition",
+  "note", "warning", "test", "task", "api", "config", "deprecated", "comment"
+];
 
 const COMMAND_HEADING = "#";
 const COMMAND_SCOPE_OPEN = "{";
@@ -45,6 +50,10 @@ function parseTableOptions(text) {
   for (const flag of flags) {
     if (flag === "borderless") options.borderless = true;
     else if (flag === "headerless") options.headerless = true;
+    else if (flag === "auto") options.width = "auto";
+    else if (/^\d+(?:\.\d+)?%$/.test(flag)) options.width = flag;
+    else if (/^\d+px$/.test(flag)) options.width = flag;
+    else if (flag === "center" || flag === "left" || flag === "right") options.align = flag;
   }
   return options;
 }
@@ -84,15 +93,7 @@ function parseSdoc(text) {
     const parsedHeading = parseHeading(cursor.current());
     cursor.next();
     const children = parseBlock(cursor, "normal");
-    const rootNode = {
-      type: "scope",
-      title: parsedHeading.title,
-      id: parsedHeading.id,
-      children,
-      hasHeading: true,
-      lineStart: scopeStartLine,
-      lineEnd: cursor.index
-    };
+    const rootNode = makeScopeNode(parsedHeading, children, true, scopeStartLine, cursor.index);
     return { nodes: [rootNode], errors: cursor.errors };
   }
 
@@ -228,6 +229,12 @@ function parseBlock(cursor, kind) {
       continue;
     }
 
+    // Line comments — skip, don't flush paragraph (invisible to AST)
+    if (trimmedLeft.startsWith("//")) {
+      cursor.next();
+      continue;
+    }
+
     if (trimmed === COMMAND_SCOPE_CLOSE) {
       flushParagraph();
       cursor.next();
@@ -348,6 +355,21 @@ function extractTrailingOpener(text) {
   return null;
 }
 
+function makeScopeNode(parsedHeading, children, hasHeading, lineStart, lineEnd, extra) {
+  const node = {
+    type: "scope",
+    title: parsedHeading.title,
+    id: parsedHeading.id,
+    children,
+    hasHeading,
+    lineStart,
+    lineEnd
+  };
+  if (parsedHeading.scopeType) node.scopeType = parsedHeading.scopeType;
+  if (extra) Object.assign(node, extra);
+  return node;
+}
+
 function parseScope(cursor) {
   const scopeStartLine = cursor.index + 1;
   const headingLine = cursor.current();
@@ -369,15 +391,7 @@ function parseScope(cursor) {
     } else {
       children = parseBlock(cursor, "normal");
     }
-    return {
-      type: "scope",
-      title: parsedHeading.title,
-      id: parsedHeading.id,
-      children,
-      hasHeading: true,
-      lineStart: scopeStartLine,
-      lineEnd: cursor.index
-    };
+    return makeScopeNode(parsedHeading, children, true, scopeStartLine, cursor.index);
   }
 
   const parsedHeading = parseHeading(headingLine);
@@ -385,38 +399,14 @@ function parseScope(cursor) {
 
   if (blockResult.blockType === "braceless") {
     const children = parseBracelessBlock(cursor);
-    return {
-      type: "scope",
-      title: parsedHeading.title,
-      id: parsedHeading.id,
-      children,
-      hasHeading: true,
-      lineStart: scopeStartLine,
-      lineEnd: cursor.index
-    };
+    return makeScopeNode(parsedHeading, children, true, scopeStartLine, cursor.index);
   }
 
   if (blockResult.blockType === "list") {
-    return {
-      type: "scope",
-      title: parsedHeading.title,
-      id: parsedHeading.id,
-      children: [blockResult.children],
-      hasHeading: true,
-      lineStart: scopeStartLine,
-      lineEnd: cursor.index
-    };
-  }
-
-  return {
-    type: "scope",
-    title: parsedHeading.title,
-    id: parsedHeading.id,
-    children: blockResult.children,
-    hasHeading: true,
-    lineStart: scopeStartLine,
-    lineEnd: cursor.index
-  };
+    return makeScopeNode(parsedHeading, [blockResult.children], true, scopeStartLine, cursor.index);
+  }
+
+  return makeScopeNode(parsedHeading, blockResult.children, true, scopeStartLine, cursor.index);
 }
 
 function tryParseInlineBlock(trimmed) {
@@ -494,6 +484,12 @@ function parseBracelessBlock(cursor) {
       break;
     }
 
+    // Line comments — skip, don't flush paragraph
+    if (trimmedLeft.startsWith("//")) {
+      cursor.next();
+      continue;
+    }
+
     if (trimmed === ",") {
       flushParagraph();
       cursor.next();
@@ -710,6 +706,9 @@ function parseListItemLine(cursor, info, allowContinuation = false) {
   const textForOpener = task ? task.text : raw;
   const trailing = extractTrailingOpener(textForOpener);
 
+  const listExtra = { shorthand: true };
+  if (task) listExtra.task = { checked: task.checked };
+
   if (trailing) {
     const parsed = parseHeadingText(trailing.text);
     cursor.next();
@@ -725,17 +724,7 @@ function parseListItemLine(cursor, info, allowContinuation = false) {
       children = parseBlock(cursor, "normal");
     }
 
-    return {
-      type: "scope",
-      title: parsed.title,
-      id: parsed.id,
-      children,
-      hasHeading: true,
-      shorthand: true,
-      task: task ? { checked: task.checked } : undefined,
-      lineStart: itemStartLine,
-      lineEnd: cursor.index
-    };
+    return makeScopeNode(parsed, children, true, itemStartLine, cursor.index, listExtra);
   }
 
   cursor.next();
@@ -756,44 +745,14 @@ function parseListItemLine(cursor, info, allowContinuation = false) {
 
   const block = parseOptionalBlock(cursor);
   if (!block) {
-    return {
-      type: "scope",
-      title: parsed.title,
-      id: parsed.id,
-      children: [],
-      hasHeading: true,
-      shorthand: true,
-      task: task ? { checked: task.checked } : undefined,
-      lineStart: itemStartLine,
-      lineEnd: cursor.index
-    };
+    return makeScopeNode(parsed, [], true, itemStartLine, cursor.index, listExtra);
   }
 
   if (block.blockType === "list") {
-    return {
-      type: "scope",
-      title: parsed.title,
-      id: parsed.id,
-      children: [block.children],
-      hasHeading: true,
-      shorthand: true,
-      task: task ? { checked: task.checked } : undefined,
-      lineStart: itemStartLine,
-      lineEnd: cursor.index
-    };
-  }
-
-  return {
-    type: "scope",
-    title: parsed.title,
-    id: parsed.id,
-    children: block.children,
-    hasHeading: true,
-    shorthand: true,
-    task: task ? { checked: task.checked } : undefined,
-    lineStart: itemStartLine,
-    lineEnd: cursor.index
-  };
+    return makeScopeNode(parsed, [block.children], true, itemStartLine, cursor.index, listExtra);
+  }
+
+  return makeScopeNode(parsed, block.children, true, itemStartLine, cursor.index, listExtra);
 }
 
 function parseImplicitListBlock(cursor, listType) {
@@ -843,16 +802,18 @@ function parseTableBody(cursor, tableStartLine, options) {
     cursor.next();
   }
 
+  const hasOptions = options.borderless || options.headerless || options.width || options.align;
+
   if (options.headerless) {
     const tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
-    if (options.borderless || options.headerless) tableNode.options = options;
+    if (hasOptions) tableNode.options = options;
     return tableNode;
   }
 
   const headers = rows.length > 0 ? rows[0] : [];
   const body = rows.slice(1);
   const tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
-  if (options.borderless) tableNode.options = options;
+  if (hasOptions) tableNode.options = options;
   return tableNode;
 }
 
@@ -911,7 +872,7 @@ function parseTaskPrefix(raw) {
 function parseFenceMetadata(meta) {
   if (!meta) return {};
   const tokens = meta.split(/\s+/).filter(Boolean);
-  let lang, src, lines;
+  let lang, src, lines, data = false;
   for (const token of tokens) {
     if (token.startsWith("src:")) {
       src = token.slice(4);
@@ -921,11 +882,13 @@ function parseFenceMetadata(meta) {
       if (match) {
         lines = { start: parseInt(match[1], 10), end: parseInt(match[2], 10) };
       }
+    } else if (token === ":data") {
+      data = true;
     } else if (!lang) {
       lang = token;
     }
   }
-  return { lang, src, lines };
+  return { lang, src, lines, data };
 }
 
 function parseCodeBlock(cursor) {
@@ -943,26 +906,37 @@ function parseCodeBlock(cursor) {
 
   const contentLines = [];
 
+  function buildCodeNode() {
+    const node = { type: "code", lang, text: stripIndent(contentLines, fenceIndent), lineStart: codeStartLine, lineEnd: cursor.index };
+    if (fenceMeta.src) node.src = fenceMeta.src;
+    if (fenceMeta.lines) node.lines = fenceMeta.lines;
+    if (fenceMeta.data) {
+      node.dataFlag = true;
+      if (lang === "json" && !node.src) {
+        try {
+          node.data = JSON.parse(node.text);
+        } catch {
+          cursor.error("Invalid JSON in :data code block.");
+        }
+      }
+    }
+    return node;
+  }
+
   while (!cursor.eof()) {
     const nextLine = cursor.current();
     const nextTrimmed = nextLine.replace(/^\s+/, "");
     const closeMatch = nextTrimmed.match(/^(`{3,})\s*$/);
     if (closeMatch && closeMatch[1].length >= fenceLen) {
       cursor.next();
-      const node = { type: "code", lang, text: stripIndent(contentLines, fenceIndent), lineStart: codeStartLine, lineEnd: cursor.index };
-      if (fenceMeta.src) node.src = fenceMeta.src;
-      if (fenceMeta.lines) node.lines = fenceMeta.lines;
-      return node;
+      return buildCodeNode();
     }
     contentLines.push(nextLine);
     cursor.next();
   }
 
   cursor.error("Unterminated code fence.");
-  const node = { type: "code", lang, text: stripIndent(contentLines, fenceIndent), lineStart: codeStartLine, lineEnd: cursor.index };
-  if (fenceMeta.src) node.src = fenceMeta.src;
-  if (fenceMeta.lines) node.lines = fenceMeta.lines;
-  return node;
+  return buildCodeNode();
 }
 
 /**
@@ -1016,12 +990,15 @@ function parseBlockquote(cursor) {
 function parseHeading(line) {
   const trimmedLeft = line.replace(/^\s+/, "");
   const raw = stripHeadingToken(trimmedLeft);
-  return parseHeadingText(raw);
+  const result = parseHeadingText(raw);
+  return result;
 }
 
 function parseHeadingText(raw) {
   const split = splitTrailingId(raw);
-  return { title: split.text.trimEnd(), id: split.id ? split.id.slice(1) : undefined };
+  const result = { title: split.text.trimEnd(), id: split.id ? split.id.slice(1) : undefined };
+  if (split.scopeType) result.scopeType = split.scopeType;
+  return result;
 }
 
 function stripHeadingToken(line) {
@@ -1033,27 +1010,49 @@ function stripHeadingToken(line) {
 }
 
 function splitTrailingId(raw) {
-  let i = raw.length - 1;
-  while (i >= 0 && /\s/.test(raw[i])) {
-    i -= 1;
-  }
+  let id = undefined;
+  let scopeType = undefined;
+  let remaining = raw;
 
-  const end = i;
-  while (i >= 0 && isIdentChar(raw[i])) {
-    i -= 1;
-  }
+  // Make up to two passes to extract trailing @id and :type in any order
+  for (let pass = 0; pass < 2; pass++) {
+    let i = remaining.length - 1;
+    while (i >= 0 && /\s/.test(remaining[i])) {
+      i -= 1;
+    }
+    if (i < 0) break;
 
-  if (i >= 0 && raw[i] === "@" && end > i && isIdentStart(raw[i + 1])) {
-    if (!isEscaped(raw, i)) {
-      if (i === 0 || /\s/.test(raw[i - 1])) {
-        const id = raw.slice(i, end + 1);
-        const text = raw.slice(0, i).trimEnd();
-        return { text, id };
+    const end = i;
+    while (i >= 0 && isIdentChar(remaining[i])) {
+      i -= 1;
+    }
+    if (i < 0 || end === i) break;
+
+    if (remaining[i] === "@" && !id && isIdentStart(remaining[i + 1])) {
+      if (!isEscaped(remaining, i)) {
+        if (i === 0 || /\s/.test(remaining[i - 1])) {
+          id = remaining.slice(i, end + 1);
+          remaining = remaining.slice(0, i).trimEnd();
+          continue;
+        }
+      }
+    }
+
+    if (remaining[i] === ":" && !scopeType && isIdentStart(remaining[i + 1])) {
+      if (i === 0 || /\s/.test(remaining[i - 1])) {
+        scopeType = remaining.slice(i + 1, end + 1);
+        remaining = remaining.slice(0, i).trimEnd();
+        continue;
       }
     }
+
+    break;
   }
 
-  return { text: raw };
+  const result = { text: remaining };
+  if (id) result.id = id;
+  if (scopeType) result.scopeType = scopeType;
+  return result;
 }
 
 function isHeadingLine(line) {
@@ -1429,13 +1428,18 @@ function renderInlineNodes(nodes) {
 }
 
 function renderScope(scope, depth, isTitleScope = false) {
+  // :comment scopes are not rendered
+  if (scope.scopeType === "comment") return "";
+
   const level = Math.min(6, Math.max(1, depth));
   const children = scope.children.map((child) => renderNode(child, depth + 1)).join("\n");
   const rootClass = isTitleScope ? " sdoc-root" : "";
   const dl = dataLineAttrs(scope);
+  const typeAttr = scope.scopeType ? ` data-scope-type="${escapeAttr(scope.scopeType)}"` : "";
+  const typeClass = scope.scopeType ? ` sdoc-scope-type-${scope.scopeType}` : "";
 
   if (scope.hasHeading === false) {
-    return `<section class="sdoc-scope sdoc-scope-noheading${rootClass}"${dl}>${children}</section>`;
+    return `<section class="sdoc-scope sdoc-scope-noheading${rootClass}${typeClass}"${typeAttr}${dl}>${children}</section>`;
   }
 
   const idAttr = scope.id ? ` id="${escapeAttr(scope.id)}"` : "";
@@ -1443,7 +1447,7 @@ function renderScope(scope, depth, isTitleScope = false) {
   const toggle = hasChildren ? `<span class="sdoc-toggle"></span>` : "";
   const heading = `<h${level}${idAttr} class="sdoc-heading sdoc-depth-${level}"${dl}>${toggle}${renderInline(scope.title)}</h${level}>`;
   const childrenHtml = children ? `\n<div class="sdoc-scope-children">${children}</div>` : "";
-  return `<section class="sdoc-scope${rootClass}">${heading}${childrenHtml}</section>`;
+  return `<section class="sdoc-scope${rootClass}${typeClass}"${typeAttr}>${heading}${childrenHtml}</section>`;
 }
 
 function renderList(list, depth) {
@@ -1536,7 +1540,16 @@ function renderTable(table) {
     .join("\n");
   const tbody = bodyRows ? `<tbody class="sdoc-table-body">${bodyRows}</tbody>` : "";
 
-  return `<table class="${classAttr}"${dl}>${thead}${thead ? "\n" : ""}${tbody}</table>`;
+  const styleParts = [];
+  if (opts.width) {
+    styleParts.push(`width:${opts.width}`);
+    if (opts.width !== "auto") styleParts.push("table-layout:fixed");
+  }
+  if (opts.align === "center") styleParts.push("margin-left:auto", "margin-right:auto");
+  else if (opts.align === "right") styleParts.push("margin-left:auto", "margin-right:0");
+  const styleAttr = styleParts.length ? ` style="${styleParts.join(";")}"` : "";
+
+  return `<table class="${classAttr}"${dl}${styleAttr}>${thead}${thead ? "\n" : ""}${tbody}</table>`;
 }
 
 function renderNode(node, depth) {
@@ -1568,7 +1581,8 @@ function renderNode(node, depth) {
         return `<div class="sdoc-math sdoc-math-block"${dl}>${renderKatex(node.text, true)}</div>`;
       }
       const langClass = node.lang ? ` class="language-${escapeAttr(node.lang)}"` : "";
-      return `<div class="sdoc-code-wrap"${dl}><pre class="sdoc-code"><code${langClass}>${escapeHtml(node.text)}</code></pre><button class="sdoc-copy-btn" title="Copy code">\u29C9</button></div>`;
+      const dataLabel = node.dataFlag ? `<span class="sdoc-data-label">data</span>` : "";
+      return `<div class="sdoc-code-wrap"${dl}>${dataLabel}<pre class="sdoc-code"><code${langClass}>${escapeHtml(node.text)}</code></pre><button class="sdoc-copy-btn" title="Copy code">\u29C9</button></div>`;
     }
     default:
       return "";
@@ -2009,6 +2023,22 @@ const DEFAULT_STYLE = `
     padding-left: 1.2rem;
   }
 
+  .sdoc-data-label {
+    position: absolute;
+    top: 6px;
+    left: 8px;
+    z-index: 1;
+    font-size: 0.65rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 1px 5px;
+    border-radius: 3px;
+    background: rgba(59, 130, 195, 0.15);
+    color: #3b82c3;
+    pointer-events: none;
+  }
+
 `;
 
 const PRINT_STYLE = `
@@ -2314,17 +2344,35 @@ function listSections(nodes) {
     id: node.id || null,
     derivedId: slugify(node.title),
     title: node.title,
+    scopeType: node.scopeType || null,
     preview: firstParagraphPreview(node.children || [], 100)
   }));
 }
 
+function collectDataBlocks(children) {
+  const data = [];
+  for (const child of children) {
+    if (child.type === "code" && child.dataFlag && child.data !== undefined) {
+      data.push(child.data);
+    }
+  }
+  return data;
+}
+
 function extractSection(nodes, sectionId) {
   const scopes = getContentScopes(nodes);
 
+  function buildResult(node) {
+    const data = collectDataBlocks(node.children || []);
+    const result = { title: node.title, content: collectPlainText(node.children || []) };
+    if (data.length) result.data = data;
+    return result;
+  }
+
   // First pass: match explicit @id (case-sensitive)
   for (const node of scopes) {
     if (node.id && node.id === sectionId) {
-      return { title: node.title, content: collectPlainText(node.children || []) };
+      return buildResult(node);
     }
   }
 
@@ -2332,13 +2380,41 @@ function extractSection(nodes, sectionId) {
   const lowerTarget = sectionId.toLowerCase();
   for (const node of scopes) {
     if (slugify(node.title).toLowerCase() === lowerTarget) {
-      return { title: node.title, content: collectPlainText(node.children || []) };
+      return buildResult(node);
     }
   }
 
   return null;
 }
 
+function extractDataBlocks(nodes) {
+  const results = [];
+  function walk(nodeList, scopeId, scopeType, scopeTitle) {
+    for (const node of nodeList) {
+      if (node.type === "code" && node.dataFlag && node.data !== undefined) {
+        results.push({
+          scopeId: scopeId || null,
+          scopeType: scopeType || null,
+          scopeTitle: scopeTitle || null,
+          data: node.data
+        });
+      }
+      if (node.type === "scope") {
+        walk(node.children || [], node.id, node.scopeType, node.title);
+      }
+      if (node.type === "list" && node.items) {
+        for (const item of node.items) {
+          if (item.type === "scope") {
+            walk(item.children || [], item.id, item.scopeType, item.title);
+          }
+        }
+      }
+    }
+  }
+  walk(nodes, null, null, null);
+  return results;
+}
+
 function extractAbout(nodes) {
   const doc = getDocumentScope(nodes);
   const children = doc ? doc.children : nodes;
@@ -2364,6 +2440,12 @@ async function resolveIncludes(nodes, resolverFn) {
           text = allLines.slice(node.lines.start - 1, node.lines.end).join("\n");
         }
         node.text = text;
+        // Re-parse JSON for :data blocks after include resolution
+        if (node.dataFlag && node.lang === "json") {
+          try {
+            node.data = JSON.parse(node.text);
+          } catch { /* leave node.data undefined — caller can check */ }
+        }
       } catch (err) {
         node.text = `// Error: Could not read ${node.src} — ${err.message}`;
       }
@@ -2392,6 +2474,8 @@ module.exports = {
   listSections,
   extractSection,
   extractAbout,
+  extractDataBlocks,
+  KNOWN_SCOPE_TYPES,
   // Low-level helpers for custom renderers (e.g. slide-renderer)
   parseInline,
   renderKatex,

package/src/slide-renderer.js

@@ -130,15 +130,26 @@ function renderTable(table) {
     .join("\n");
   const tbody = bodyRows ? `<tbody>\n${bodyRows}\n</tbody>` : "";
 
-  return `<table${classAttr}>${thead}${thead ? "\n" : ""}${tbody}</table>`;
+  const styleParts = [];
+  if (opts.width) {
+    styleParts.push(`width:${opts.width}`);
+    if (opts.width !== "auto") styleParts.push("table-layout:fixed");
+  }
+  if (opts.align === "center") styleParts.push("margin-left:auto", "margin-right:auto");
+  else if (opts.align === "right") styleParts.push("margin-left:auto", "margin-right:0");
+  const styleAttr = styleParts.length ? ` style="${styleParts.join(";")}"` : "";
+
+  return `<table${classAttr}${styleAttr}>${thead}${thead ? "\n" : ""}${tbody}</table>`;
 }
 
 function renderNestedScope(scope) {
+  if (scope.scopeType === "comment") return "";
   const heading = scope.hasHeading !== false && scope.title
     ? `<h3>${renderInline(scope.title)}</h3>`
     : "";
+  const typeAttr = scope.scopeType ? ` data-scope-type="${escapeAttr(scope.scopeType)}"` : "";
   const children = scope.children.map((child) => renderNode(child)).join("\n");
-  return `<section>${heading}\n${children}</section>`;
+  return `<section${typeAttr}>${heading}\n${children}</section>`;
 }
 
 function renderChildren(nodes) {
@@ -179,6 +190,10 @@ function extractNotes(children) {
   const notes = [];
   const rest = [];
   for (const child of children) {
+    if (child.type === "scope" && child.scopeType === "comment") {
+      // :comment scopes are excluded from both notes and content
+      continue;
+    }
     if (child.type === "scope" && child.id && child.id.toLowerCase() === "notes") {
       notes.push(child);
     } else {
@@ -208,8 +223,8 @@ function renderSlide(scope, slideIndex, overlayHtml) {
   let bodyHtml;
   if (config.layout === "two-column") {
     // In two-column layout, child scopes become columns
-    const columns = contentNodes.filter((n) => n.type === "scope");
-    const nonColumns = contentNodes.filter((n) => n.type !== "scope");
+    const columns = contentNodes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
+    const nonColumns = contentNodes.filter((n) => n.type !== "scope" || n.scopeType === "comment");
     const preamble = nonColumns.length ? renderChildren(nonColumns) : "";
     const columnsHtml = columns
       .map((col) => {
@@ -256,8 +271,8 @@ function renderSlides(nodes, options = {}) {
     slideScopes = nodes;
   }
 
-  // Filter to scope nodes only (skip stray paragraphs at top level)
-  const slides = slideScopes.filter((n) => n.type === "scope");
+  // Filter to scope nodes only (skip stray paragraphs and :comment scopes)
+  const slides = slideScopes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
 
   // Build per-slide footer: <  CONFIDENTIAL  ---gap---  Company  >
   const footerParts = [];