Meeting № 28 Summary

[devhelpr]

Recording of meeting

Full transcription

Meeting № 28 Summary

Major Discussion Points

• Specification Versioning and Preparation
  The team copied the spec to a new folder and renamed it to “version identify” from draft 0.05 to 0.051 to begin making actual progress on implementations and improvements.

• Nesting Canvases in OKIF
  Discussed the current primitive support for nesting canvases by referencing external OKIF files as node resources, but noted the lack of formal spec explanation on how nested OKIF files are represented or linked, and how this affects node relationships.

• Prioritization of Work: Implementation vs Feature Extensions
  Members debated whether to prioritize improving the spec’s nesting capabilities or focus on more complete implementations, emphasizing that support for Obsidian Canvas <-> OKIF round-trip is currently the highest-value use case due to its simplicity and existing strong adoption.

• Root Node Definition in OKIF Canvases
  Explored how to designate a root node within an OKIF canvas file, considering options such as reserving node index zero or explicitly linking the root node by a dedicated property like rootNode. The group leaned towards an explicit property approach to avoid "magic strings" or indices, aligning with design principles.

• Node Parent-Child Relationships and Implicit Root
  Discussed that nodes without explicit parents are implicitly children of the root node, and considered redundancy of explicitly stating this relation in data files. It was agreed to allow explicit mentioning for clarity but note it is implied by default.

• Default Styling and Themes Propagation
  Covered the absence of formal default styling in the spec (e.g., default font size, colors), with the design principle that themes attached to a node propagate to descendants. If absent, defaults must be defined (e.g., font size 12).

• Node Transform Properties: Position, Scale, Rotation
  Noted that scale was moved into a node transform extension, but rotation remains a core node property with no explicit extension. This separation may seem inconsistent but is accepted due to conceptual differences in how they affect node transformation hierarchies.

• Library and Monorepo Setup for Tooling & Contributions
  Emphasized the importance of creating a well-structured monorepo with a shared library and CLI tools to manage OKIF <-> JSON canvas conversion workflows. Suggested starting agile with actual implementations to learn and align rather than top-down design, reusing Michael’s existing app code as a starting point for the library extraction.

• Representing Nested Canvases as Resources with Node Overrides
  Clarified that nested canvases are represented as node resources linking to other OKIF files, with the importing node overriding position or other transform properties for each instance, enabling multiple placements of the same nested canvas.

• Root Node Constraints and Validity Rules
  Defined that a root node cannot be a child of another node and that only one root node is allowed per canvas file. Multiple top-level nodes must be grouped under a single root node representing the entire document.

• View and Camera Settings / Metadata Extensions
  Discussed adding extensions to specify initial camera zoom or viewport rectangles, as well as document-level metadata including tool information and modification dates. Some data should live in a dedicated top-level section rather than as a node extension to remain applicable to the whole file.

• General Agreement on Nesting Simplicity and Further Specification Work
  Concluded that with a clear definition of root nodes and transforms, nesting canvases should be straightforward to implement in the spec.

---

Action Items

• Extract a shared library from Michael’s existing app to provide reusable OKIF <-> JSON canvas conversion functionality, hosted in a monorepo with CLI tools to support multiple implementations and testing.

• Define and update the specification to explicitly require a root node property (suggested name rootNode) with clear semantics about its uniqueness and relation to other nodes.

• Draft detailed spec text describing parent-child relationships, including that nodes without parents are implicitly children of the root node, and clarify the handling of redundant explicit parent links.

• Define default appearance and theme propagation rules for canvases, including fallback values for font size and colors if no theme is specified.

• Clarify the rationale and documentation for node transform properties, especially why rotation remains core while scale is an extension.

• Draft the nesting canvases section taking into account the root node system and override mechanics for nested OKIF file instances.

• Consider defining a top-level metadata section for document-wide properties including camera/view information and author/tool metadata, separate from node extensions.

• Plan to create examples and test cases showing nested OKIF files and how overrides work, aiding implementors.

---

Takeaways

• Obsidian Canvas integration with OKIF is considered highly valuable due to its user base and relative simplicity, making it a practical focus for early full implementations.

• Explicit linking of the root node by ID is preferred over magic strings or indices, supporting clarity and ease of use by humans and tools such as LLMs.

• Nodes without parents are implicitly children of the root node, simplifying hierarchy assumptions.

• Nesting canvases, once root nodes and transforms are clearly specified, is conceptually straightforward and leverages existing inheritance and override mechanisms.

• A well-structured monorepo with libraries and CLI tooling will facilitate contributions and enable iterative improvements to the spec and implementations.

• Some decisions (like separation of rotation and scale into core vs extension properties) are pragmatic, even if they feel inconsistent, and should be well documented.

• Metadata and document-level properties are better suited to top-level structures than node-level extensions for clarity and extensibility.